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.
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:
provider_uriwhich 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_urito 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
- 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.
- Use the
Sending information to mnemonic to set up the provider configuration
client_id from the previous step to mnemonic to configure the provider.
Next, we need some public information about your provider:
- The OpenID Configuration URI which contains all settings needed to configure the client, e.g.
Or, if the OpenID server is not publicly available on Internet, or does not have a configuration URI, we need:
- 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.
upnIf 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
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.
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
The certificate to submit to Argus should be the full base64-encoded JWKS certificate mentioned in the openid-configuration.
The issuer must be the same as the "iss" claim returned in the id_token.
The issuer should be explicitly stated in
If issuer is not set, the issuer will default to expect a prefix of the providerURI.
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
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.
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
Note: How this behaviour is implemented is up to the provider. Argus cannot control the details of how the provider verifies the user.
Some providers do not support response_type=id_token which is the default flow.
responseType option you can select type
However, note that the current implementation requires that the provider redirects back with a valid
Tested provider settings
- Well known configuration:
- Use responseType=idToken (default)
- Use default issuer
- Use userName claim
- Use X509 certificate or JWKS
- 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_uriof 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
claimsMappingis present and uniquely identifies users coming from this provider.
- The provider MUST transparantly return the
statevariable as it is passed to the provider from the client
- The provider MUST accept and use the
noncepassed by the client into the ID-token
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")
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".
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:
(where myprovider is the shortname of the provider to use, as defined above).
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:
- No labels