OpenID Connect Support#

The Argus Identity Provider supports OpenID Connect, allowing integration with most standard OpenID-supporting clients.

By integrating using OpenID Connect, the 3rd party application can

authenticate users from Argus
get information about the current user from Argus (such as name, email, phone, user image)
fetch the users group membership
custom claims (which are supported by Argus)

Enabling OpenID Connect#

To enable OpenID connect, the client must specify scope=openid to the authorization request. Example:

https://portal.mnemonic.no/spa/oauth/authorize?client_id=021269c5-04c3-4399-a206-32659c489803&redirect_uri=https://my.application/oauth/callback&response_type=code&scope=openid

The client can request additional scopes supported by Argus, to add more claims to the id token. Scopes should be listed as a space-delimited list of scope names:

Example plain text scopes: openid groups profile
Example URI-encoded scopes: openid%20groups%20profile

Valid scopes in Argus#

groups: adds a claim groups which contains a JSON array of group shortnames:

"groups": [
"mygroup1",
"mygroup2"
]

groupstring: adds a claim “groupstring” with a string-encoded JSON array of group shortnames (which is required by some OpenID clients)

"groupstring": "[\"mygroup1\",\"mygroup2\"]"

Note

groups and groupstring claims are deprecated, as the groups to expose to 3rd party clients need custom configuration to control which groups to expose. See Custom claims below.

customer: adds three claims with information about the domain and customer which the identified user is assigned to

Note

this does not provide any information about permissions given to this user

"customer_id": 1,
"domain_id": 1,
"customer_shortname": "mycustomer",
"customer_name": "My Customer"

email: adds a claim email

"email": "user@domain.com"

profile: adds claims for username, name and picture URI

"username": "myusername",
"name": "My Users Name",
"picture": "https://api.mnemonic.no/users/v2/user/1000/picture"

clientip: adds a claim “client_ip” which contains the IP which this user session is bound to (which may be used to verify that requests are indeed coming from this IP).

Note

This is the IP as seen by Argus, so will not show a users private IP inside a NATed network or behind a proxy..

"client_ip": "94.127.56.1"

Custom OpenID Claims#

Argus supports a set of custom claims, which can be configured when setting up the client, to provide specific mapping.

User Groups Claim#

This provider will generate a claim “groups” containing a list of group shortnames which the user is member of, from a list of allowed groups. This allows the client to be configured to only expose a certain set of groups.

The “stringified” option allows the client to be configured to return as a “stringified” claim, with a json string of a json array, which some OpenID clients require. The default is to return a list claim with each group shortname as a list item.

To configure this provider, use the following configuration format

{
  "openIDCustomClaims": [
    {
      "provider": "userGroups",
      "configuration": {
        "stringified": false,
        "allowedGroups": ["group1", "group2"]
      }
    }
  ]
}

With the above configuration, if the current user was member of “group1” (but not group2), it would produce the following claim:

"groups": ["group1"]

Note

This provider should be used to replace the “groups” or “groupstring” scope

Function Role Mapping Claim#

This provider will generate a custom claim containing a list of “roles”, where each role is mapped to an Argus function. Of the configured roles, the claim will be populated only with the roles for which the user is granted. If the OAuth client is defined for a specific customer, the function must be granted for that customer.

Example:

We want to map functions argusFunction1 and argusFunction2 for the clients customer to roles customRole1 and customRole2.

if the user has permission to argusFunction1 for the clients customer, the provider would create the claim "TheCustomClaimName": ["customRole1"]
if the user has permission to argusFunction2 for the clients customer, the provider would create the claim "TheCustomClaimName": ["customRole2"]
if the user has permission to both argusFunction1 and argusFunction2 for the clients customer,

To configure this provider, use the following configuration format

{
  "openIDCustomClaims": [
    {
      "provider": "functionRoleMapping",
      "configuration": {
        "claimName": "TheCustomClaimName",
        "roleMapping": {
          "argusFunction1": "customRole1",
          "argusFunction2": "customRole2"
        }
      }
    }
  ]
}

The provider would create the claim

"TheCustomClaimName": ["customRole1", "customRole2"]