Description

According to the RFC 6749 an application (client) owns the credentials and uses them to get an access token from the Authorization Server.

Authentication happens in a single request-response conversation when the request contains client credentials, grant_type (client_credentials) and optionally scope.

The response contains an access token, its type and expiration. Refresh token should not be included.

There are two main use cases for Client Credentials Grant in SSO:

• Single application use case: token grants access to the application itself;

• Authorized access use case: token grants access to a number of server applications according to the service user rights (group membership, authentication method allowed for service user account).

Single application use case

Description

In a single application use case a token grants access to only application itself. There is no authorization for this case.

Configuration

Client Credentials Grant can be configured either with SSO Management UI or SSO Management API. This instruction covers the UI. Refer to Configuring impersonation with Management API - SSO for API instructions.

Prerequisites:

1. Site Example, OAuth 2.0 application Client1 and group Group1 exist in SSO.

2. Application Client1 has client_credentials grant type in its metadata:

   ...
    "grant_types": [
       "client_credentials"
     ]
   ...

The following steps are required to configure single application access:

1. Create and enable authentication method as described in OAuth 2.0 Client Credentials Grant authentication method - SSO

2. Add this method to site Example.

3. Allow the method for application Client1

4. Allow the method for group Group1.

5. Allow Group1 to access application Client1.

Now it should be possible to get the token with Client1 application credentials:

POST {{baseUrl}}/uas/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=oidc&client_id=Client1&client_secret=secret

Authorized access use case

Description

In authorized access use case a token issued with client credentials of one application (Client1) can grant access to other applications (Server1…ServerN). Authorization is based on access rights of impersonated user (User1).

For example when a Client1 is a command line script, Server1 is SSO Management API and Server2 is CustomerID API.

The configuration with 2 server applications shown below.

The Client application is impersonating a User1 which is a member of 2 groups. Each of these groups has access to one server application that should be accessed by the Client1 application. Authorization policies that can be configured for server applications are omitted from the configuration example as it is not mandatory.

If Client1 application is using the token to access to itself then User1 account should be a member of the group which is allowed to access the application.

Configuration

Prerequisites:

1. Site Example, OAuth 2.0 applications Client1, Server1, Server2, user account User1 and groups Group1, Group2 exist in SSO.

2. Application Client1 has client_credentials grant type and client IDs of server applications in its metadata:

...
 "grant_types": [
    "client_credentials"
  ],
  "scope": "openid Server1 Server2"
...

3. Server applications does not have any grant types or scopes:

   ...
    "grant_types": [],
    "scope": ""
   ...

The following steps are required to configure multiple applications access:

1. Create and enable authentication method as described in ​OAuth 2.0 Client Credentials Grant authentication method - SSO

2. Add this method to site Example.

3. Allow the method for applications: Client1, Server1 and Server2.

4. Allow Group1 to access application Server1.

5. Allow Group2 to access application Server2.

6. Allow the method for user account User1.

7. Make User1 a member of Group1 and Group2.

8. Add Client1 application to the list of applications impersonating an account User1.

Now it should be possible to get the token for Server1 or Server2 with Client1 application credentials:

POST {{baseUrl}}/uas/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=Server2&client_id=Client1&client_secret=secret

Then the token can be introspected:

POST {{baseUrl}}/uas/oauth2/introspection
Authorization: Basic Server2 secret
Content-Type: application/x-www-form-urlencoded

token={{accessToken}}

{
  "usn": "Client1",
  "iss": "https://localhost:8443/uas",
  "aud": [
    "Server2"
  ],
  "exp": 1696336474,
  "iat": 1696332874,
  "auth_time": 1696332874,
  "amr": [
    "https://localhost:8443/uas/saml2/names/ac/client.credentials.1"
  ],
  "azp": "Server2",
  "session_index": "_2d4a2d858137b04ca0154aac6a651988a5b63089",
  "client.credentials.1.grant_type": [
    "client_credentials"
  ],
  "client.credentials.1.issuer_dn": [
    "cn=Client1,ou=Example,cn=Ubilogin,dc=test"
  ],
  "client.credentials.1.issuer": [
    "Client1"
  ],
  "client.credentials.1.dn": [
    "cn=User1,ou=Example,cn=Ubilogin,dc=test"
  ],
  "client.credentials.1.ldap": [
    "ldap:///cn=Ubilogin,dc=test"
  ],
  "token_type": "access_token",
  "active": true,
  "client_id": "Client1",
  "expires_in": 3596
}

Also user information can be obtained using received token:

POST {{baseUrl}}/uas/oauth2/userinfo
Authorization: Bearer {{accessToken}}

{
  "usn": "Client1",
  "iss": "https://localhost:8443/uas",
  "aud": [
    "Server2",
    "Client1"
  ],
  "exp": 1696336474,
  "iat": 1696333379,
  "auth_time": 1696332874,
  "amr": [
    "https://localhost:8443/uas/saml2/names/ac/client.credentials.1"
  ],
  "azp": "Client1",
  "session_index": "_236ae5a56862435c4f19e6d6b55d90ae97e79df4",
  "client.credentials.1.grant_type": [
    "client_credentials"
  ],
  "client.credentials.1.issuer_dn": [
    "cn=Client1,ou=Example,cn=Ubilogin,dc=test"
  ],
  "client.credentials.1.issuer": [
    "Client1"
  ],
  "client.credentials.1.dn": [
    "cn=User1,ou=Example,cn=Ubilogin,dc=test"
  ],
  "client.credentials.1.ldap": [
    "ldap:///cn=Ubilogin,dc=test"
  ]
}

Security risk and mitigation

TBD