Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Overview

This guide addresses how to set up integration with an external OpenID identity provider, i.e. allowing users to log in to Argus using an external OpenID provider, such as ADFS, Azure AD or other standard OpenID providers.

Tip

To set up your OpenID enabled application with Argus as the identity provider, see Argus Identity Provider Integration Guide


OpenID Provider integration

Understanding Argus OpenID Provider integration

Using an external OpenID provider for authentication is done by defining the provider in Argus with:

  • A provider_uri which will be redirected to when authentication is needed
  • An OAuth client_id to use to identify Argus as the authorizing application
  • A X509 certificate or JWKS file from the provider, which is used to verify the ID-tokens from the provider

When defined, users may log in to Argus using the OpenID Implicit Flow

  • Argus will redirect the user to the configured providers login page, with a callback URI back to Argus
  • Once authenticated, the user will be redirected back to Argus with an OpenID ID-token
  • Argus will decode and validate the token using the providers certificate, and identify the user account from the claims in the ID-token
  • If successfully validated, Argus will initiate a session for the corresponding Argus user

Defining the OpenID Client in your provider

  • First, agree on a "provider shortname", which will be used to identify the provider in Argus, e.g. "myprovider"
  • This defines the redirect_uri to use: https://portal.mnemonic.no/spa/authentication/openid/provider/myprovider/authenticate
  • Next, you need to set up Argus as an OpenID Client in your provider:
    • Use the redirect_uri above 
    • Use a random client_id (if not generated by your provider)
    • No client secret is necessary, as this is not used in the OpenID flow used.

Sending information to mnemonic to set up the provider configuration

Send the client_id from the previous step to mnemonic to configure the provider.

Next, we need some public information about your provider:

Either:

  • The OpenID Configuration URI which contains all settings needed to configure the client, e.g. https://<your-openid-provider>/.well-known/openid-configuration

Or, if the OpenID server is not publicly available on Internet, or does not have a configuration URI, we need:

  • The provider_uri
  • The issuer to use
  • The complete contents of the JWKS endpoint (JSON output)

In addition, you need to know which claim should be used for identity mapping, e.g. email or upn
If the claim to use is not known/configured, this needs to be tested during later setup, and may require some re-configuration on both sides.

Setting up Argus to work with an external OpenID Provider

Defining new OpenID Provider

To define a new OpenID provider, use the /authentication/v1/openid/provider  endpoint:

No Format
curl -XPOST -H"Argus-API-Key: my/api/key" https://api.mnemonic.no/authentication/v1/openid/provider -d
{
"customer": "mycustomer",
"shortName": "myprovider",
"name": "My ADFS Provider",
"clientID": "argusClient",
"certificate": "MIIEtjCCAp4CCQDQSsrUHtwMmDANBgkqhkiG9w0BAQUFADAdMRs...",
"providerURI": "https://my.provider/oidc/authorize",
"issuer": "https://my.provider",
"claimsMapping": {
  "userName": "user"
 }
}

In this setup, the claimsMapping specifies to use the claim "user", which should uniquely identify a user from this provider.
This could be a username, email, user-ID or similar, as long as it is unique, and always returns the same value for the same user.


Tip

The certificate should be the same certificate as is defined in well-known OpenID configuration of your provider, which for an ADFS server can be found under

https://<your-openid-provider>/.well-known/openid-configuration

The certificate to submit to Argus should be the full base64-encoded JWKS certificate mentioned in the openid-configuration.

Tip

The issuer must be the same as the "iss" claim returned in the id_token. 

The issuer should be explicitly stated in https://<your-openid-provider>/.well-known/openid-configuration

If issuer is not set, the issuer will default to expect a prefix of the providerURI.

Tip

Some providers do not expose a certificate, instead the JWKS of the provider specifies a set of public key parameters.
Instead of passing a base64-encoded X509 certificate, you can pass an entire base64-encoded JWKS file.

You should find the URL to your providers JWKS file in https://<your-openid-provider>/.well-known/openid-configuration


No Format
curl -XPOST -H"Argus-API-Key: my/api/key" https://api.mnemonic.no/authentication/v1/openid/provider -d 
{ 
...
"jwks": "MIIEtjCCAp4CCQDQSsrUHtwMmDANBgkqhkiG9w0BAQUFADAdMRs..."
...
}
Tip

When performing authorization of sensitive operations, it is advised to set up the OpenID provider to require the users username/password to verify user presence.
Optionally, user presence may be confirmed without requiring password, depending on the providers OpenID support.

The option authorizationPrompt  supports the three following OpenID options:

  • login - require user to enter username and password
  • consent - ask user to confirm without prompting for password
  • none - perform a standard authentication flow, do not require user confirmation


No Format
curl -XPOST -H"Argus-API-Key: my/api/key" https://api.mnemonic.no/authentication/v1/openid/provider -d 
{ 
...
"authorizationPrompt": "MIIEtjCCAp4CCQDQSsrUHtwMmDANBgkqhkiG9w0BAQUFADAdMRs..."
...
}

Note: How this behaviour is implemented is up to the provider. Argus cannot control the details of how the provider verifies the user.

Tip

Some providers do not support response_type=id_token which is the default flow.

Using the responseType  option you can select type token  or idTokenAndToken.

However, note that the current implementation requires that the provider redirects back with a valid id_token  parameter.

No Format
curl -XPOST -H"Argus-API-Key: my/api/key" https://api.mnemonic.no/authentication/v1/openid/provider -d 
{ 
...
"responseType": "token"
...
}

Tested provider settings

ADFS 2016

  • Well known configuration: https://<your-adfs-server>/adfs/.well-known/openid-configuration
  • Use responseType=idToken (default)
  • Use default issuer
  • Use userName claim upn
  • Use X509 certificate or JWKS

Azure AD

Cognito

  • Use responseType=token 
  • Use explicit issuer
  • Use JWKS

Setting up your OpenID provider with Argus

To set up the OpenID provider, you need to do the following:

  • Define a new OpenID client with a matching client_id  ("argusClient" in the example above)
  • Define the redirect_uri of the provider to be https://portal.mnemonic.no/spa/authentication/openid/provider/myprovider/authenticate
    where "myprovider" is the shortname or ID of the provider, as defined above
  • Make sure that the claim specified in the claimsMapping is present and uniquely identifies users coming from this provider.
  • The provider MUST transparantly return the state  variable as it is passed to the provider from the client
  • The provider MUST accept and use the nonce passed by the client into the ID-token


Warning

When defining Argus as an OpenID client for your provider, make sure to only allow the specified redirect_uri in your providers redirect_uri whitelist . The provider should reject any authorization attempt if the client specifies any other URI.
This is an important security control to avoid that an unauthorized party can trick a client into authenticating and retrieving an ID-token from your provider, and pass it to the attacker, which can then log in to Argus on behalf of your user.

You should therefore verify that your OpenID provider correctly rejects any authentication attempt for the configured client_id if the redirect_uri does not match.


Binding users to OpenID provider

Currently, Argus does not auto-discover users, so user must be added to Argus before they can log in.

To enable OpenID authentication for a user, you need to

  • Enable OPENID as an authentication method for the user
  • Bind the user to the registered OpenID provider
  • Bind the user to the external username which will be returned in the OpenID ID-token, in the configured claim (e.g. "user")

Example:

No Format
# this enables OpenID authentication for the user "myuser"
curl -XPUT -H"Argus-API-Key: my/api/key" https://api.mnemonic.no/authentication/v1/user/myuser/enable/openid

# this binds the user "myuser" to be logged in using the "myprovider" OpenID provider, given that the ID-token returns a "user" claim with the value "user@domain.com"
curl -XPUT -H"Argus-API-Key: my/api/key" https://api.mnemonic.no/authentication/v1/user/myuser/openid
{
"mappedUserName": "user@domain.com",
"provider": "myprovider"
}


Logging on to Argus using an external OpenID Provider

First time trying to log in using an OpenID provider


Because Argus supports multiple OpenID providers, Argus cannot redirect the user to any OpenID provider for authentication without any prior knowledge.

Therefore, a user trying to log in to Argus using OpenID for the first time, will be rejected with the error message "OpenID authentication is not enabled for this user".

Image Modified

Initializing users to log in using your OpenID provider

To initialize a user/browser to log in to Argus, you need to pass a hint to Argus with the name or ID of the provider that the user should be redirected to.

To do this, inform your users to use the following link to log in to Argus:

https://portal.mnemonic.no/spa/authentication/login/openid?provider=myprovider

(where myprovider is the shortname of the provider to use, as defined above).


Tip

Once the user clicks the link above, Argus will store the name of the provider to use in the local storage of the browser, so the user does not have to remember the link.

However, note that if the user visits Argus using another browser, or using the browsers incognito mode, the browser will not have the provider name in store. 
In that case, the user has use the same link again.


After the first successful login, the browser will remember to use the OpenID provider again for the next visit. 
The user will have to confirm before the authentication is started, by clicking the "Authenticate" button:

Image Modified





Table of Contents