OAuth 2.0 - Resource Owner Password Credentials grant

Overview

NOTE: Resource Owner Password Credentials Grant will be deprecated in OAuth 2.1. Please think twice before using this.

The Resource Owner Password Credentials Grant (defined in RFC 6749, section 4.3) can be used directly as an authorization grant to obtain an access token, and optionally a refresh token. This grant should only be used when there is a high degree of trust between the user and the client and when other authorization flows are not available.

This grant type can eliminate the need for the client to store the user credentials for future use, by exchanging the credentials with a long-lived access token or refresh token.

How to implement the Resource Owner Password Credentials

Client's Grant Type

The client's grant type property must be to password.

Register an Identify local user

You need to create a new Identify user:

From the Safewhere Admin application list, you can create an OAuth 2.0 application, then open its sub tabs and update the following:

• On its connection tab:
  • Client ID: Specifies the unique ID of the application. Client ID is case-sensitive.
  • Client secret: Specifies the Client secret of the application. Client secret is case-sensitive.
  • Token endpoint authentication method: Specifies the client authentication method to the token endpoint.
  • Allowed Callback URIs: Specifies the redirect URL after successful authentication, e.g https://identifydomain/runtime/
  • Application name: Specifies the name of the application
  • Security token audiences: Specifies the recipients (usually in URI format) that issued access tokens are intended for. When the resource parameter is missing, an access token is issued with its 'aud' claim set to all configured audiences.

• On its security tab:
  • JWS algorithm: Either RSASigning or HMACSymmetric.
  • Symmetric signing key: Used to generate a HMAC Symmetric signing key; key can be 32-byte, 48-byte, or 64-byte. You can then either copy the key and paste it to the configuration or check the appropriate check box and click Select key to apply it.
  • Allow password flow: This setting must be True.

• Client ID: specifies the unique ID of the application. Client ID is case-sensitive.
• client secret: specifies the client secret of the application. Client secret is case-sensitive.
• Token endpoint authentication method: specifies the client authentication method to the token endpoint.
• Allowed Callback URIs: specifies the redirect URL after successful authentication, e.g. https://identifydomain/runtime/
• Application name: specifies the name of the application
• Security token audiences: Specifies the recipients (usually in URI format) that issued access tokens are intended for. When the resource parameter is missing, access tokens are issued for all configured audiences.

• Security tab:

  • JWS algorithm: either RSASigning or HMACSymmetric.
  • Symmetric signing key: used to generate a HMAC Symmetric signing key; key can be 32-byte, 48-byte, or 64-byte. You can then either copy the key and paste it to the configuration or check the appropriate check box and click Select key to apply it.
  • Allow password flow: this setting must be True.

Ask for a token

To ask Identify for tokens for any of your authorized client applications, perform a POST operation to the token endpoint:

https://#identifydomain/runtime/oauth2/token.idp

URI parameters:

Parameter	Description
client_id	Your application's client ID
client_secret	Your application's client secret
grant_type	This must be "password"
username	The Identify username
password	The Identify user password to login to the Identify

The response contains a signed JSON Web Token, the token's type (which is Bearer), and in how much time it expires in Unix time (3600 seconds, which means 1 hour).

{
    "scope": "identify*empty",
    "token_type": "Bearer",
    "access_token": "eyJhbGciO...R1FVrH5g",
    "expires_in": 3600
}

If you decode the access_token, you will see that it contains the following claims:

{
  "unique_name": "identifyuser1",
  "sub": "identifyuser1",
  "name": "identifyuser1",
  "urn:internal:userid": "f60756f6-3f8f-4723-ad52-123456",
  "token_usage": "access_token",
  "jti": "2b94a884-1cef-4f2b-8f3f-123456",
  "scope": "identify*empty",
  "aud": "https://idp.safewhere.local/runtime/",
  "azp": "client_connect_sample_id1",
  "iat": 1590374925,
  "nbf": 1590374925,
  "exp": 1590378525,
  "iss": "https://idp.safewhere.local/runtime/oauth2"
}

FAQ

Q: I would like to include the refresh_token on the response. What can I do?

A: you can enable the "Allow refresh token" setting at the security tab of the OAuth 2.0 application connection.

Here is a sample for the response:

{
    "scope": "offline_access",
    "token_type": "Bearer",
    "access_token": "eyJhbGciO...zn9LGXg",
    "expires_in": 3600,
    "refresh_token": "CfDJ8KrDPV...1UdTBDln4s"
}

Q: I want to use the "dk:gov:saml:attribute:CprNumberIdentifier" claim type for username, not the Name claim type. What can I do?

A: You can follow these steps:

• You create the Identify local user who has the value of the "dk:gov:saml:attribute:CprNumberIdentifier" claim.
• You create a NameID transformation whose source is "dk:gov:saml:attribute:CprNumberIdentifier"
• You apply the claim transformation to the OAuth 2.0 application

Here is the sample result:

{
    "scope": "identify*empty",
    "token_type": "Bearer",
    "access_token": "eyJhbGci...dhPSxfhNVg",
    "expires_in": 3600
}

If you decode the access_token you will see that it contains the following claims:

{
  "unique_name": "admin",
  "sub": "12345678",
  "dk:gov:saml:attribute:CprNumberIdentifier": "12345678",
  "urn:anyid:role": "HelloAngel",
  "urn:identify:rest-api:role": "HelloAngel",
  "name": "12345678",
  "urn:internal:userid": "ca7b48ac-830f-4126-bdc2-123456",
  "token_usage": "access_token",
  "jti": "e4f0625a-f57a-43b1-8b77-12123",
  "scope": "identify*empty",
  "aud": "https://idp.safewhere.local/runtime/",
  "azp": "client_connect_sample_id1",
  "iat": 1590389355,
  "nbf": 1590389355,
  "exp": 1590392955,
  "iss": "https://idp.safewhere.local/runtime/oauth2"
}