Authorization Code

This authentication flow is suitable for API Clients that can securely maintain a client secret between themselves and Stems Accounts because authenticatiing requires a Client ID and a Client Secret. This authentication flow is not suitable for insecured applications such client-side applications such as React JS and Angular JS applications.

When using this authentication flow, an Authorization Code is issued to the API Client, which can then exchange it for an ID Token and an Access Token. This provides the benefit of not exposing any tokens to the browser and possibly other malicious applications with access to the browser.

The Authorization Code flow goes through the following steps:

1. The client sends a request to Stems Accounts' Authorization Endpoint
2. Stems Accounts responds back with an Authorization Code
3. The client issues a request to Stems Accounts' Token Endpoint using the obtained Authorization Code
4. Stems Accounts responds back with an ID Token, an Access Token and optionally a Refresh Token
5. The client validates the ID Token

Authentication Request

To obtain an Authorization Code, the API Client starts by redirecting the user to Stems Accounts's Authorization Endpoint. The request must include the following querystring parameters:

A typical authentication request to Stems Accounts' Authorization Endpoint using the Authorization Code flow would look like the following example:

GET /auth/connect/authorize?
client_id=YOUR_CLIENT_ID
&redirect_uri=http:%2f%2fcontoso.com
&response_mode=form_post
&response_type=code+id_token
&scope=openid+profile+roles+email+offline_access+resources_accounts_api
&state=9087BDF7DF9G7HDF9HG7FGH
&nonce=636704982903393456 HTTP/1.1
Host: accounts.stems.com.au

If the request to the Authorization Endpoint is successful, Stems Accounts will issue a POST request to the url specified in the redirect_uri with the Authorization Code in the body of the request if the response_form was present in the authentication request.

The body of the response from Stems Accounts will include the following form data:

When the response_form is not included in the authentication request, Stems Accounts will redirect back to the redirect_uri with the Authorization Code included in the url query string as in the example below:

GET /?code=85ff37999de045455b6eea8f194235fe
&state=345G2KJHG32JK5G34KLH2F46HK
&session_state=59306c731065bd5bef7d78ec90b4dc5a HTTP/1.1
Host: contoso.com

The Authorization Endpoint could return errors if the API Client is not setup properly or the request had invalid or missing parameters. When an error occurs, the Authorization Endpoint will return to the API Client's redirect_uri with an error parameter containing an error code and an optional error_description fragment parameter with details about the error.

Token Request

Once the Authorization Code has been received from Stems Accounts, the API Client can issue a POST request to the Stems Accounts' Token Endpoint. The request MUST include the following form parameters:

A typical token request will look like the following example:

POST /auth/connect/token HTTP/1.1
Host: accounts.stems.com.au
Content-Type: application/x-www-form-urlencoded
                
client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&grant_type=authorization_code
&code=69241171b4663455345a992b81
&redirect_uri=http%3A%2F%2Fcontoso.com

If the request is successful, Stems Accounts will return a JSON response that includes the ID Token, Access Token and optionally a Refresh Token. A Refresh Token will only be returned if the authentication request included the offline_access scope.

The JSON object returned from Stems Accounts includes the following properties:

The JSON object returned in response to a token request would look like the following example:

{
    "id_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6ImEzck1VhdfghdfghuYW1lIjoiYmlkb2ZA",
    "access_token":"3f867823462836289d32ae2636",
    "expires_in":1800,
    "token_type":"Bearer",
    "refresh_token":"9cbd79ed0394872394747e22b5e0d2c2f"
}

If the token request fails, Stems Accounts will return a JSON object with details about the error. The following is an example error response

{
    "error":"unauthorized_client"
}

ID Token Validation

Once the API Client has received the ID Token, it is strongly recommended that it is validated to make sure it hasn't been tampered with. To validate it, you can issue a POST request to Stems Accounts' Token Validation Endpoint

The request to the Token Validation Endpoint must include the following form parameters in the body of the request:

A typical request to the Token Validation Endpoint would look like the following example:

POST /auth/connect/identitytokenvalidation HTTP/1.1
Host: accounts.stems.com.au
Content-Type: application/x-www-form-urlencoded
                
client_id=YOUR_CLIENT_ID
&token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6ImEzck1VZ01Gdjl0UGNsTGE2eUYzekF

If the response is successful, Stems Accounts will return the ID Token decrypted in a JSON object with the following properties:

The JSON object returned might contain other properties such as idp,name, given_name and family_name but these properties don't need to be validated. An example JSON response would look like the following example:

{
    "iss":"https://accounts.stems.com.au/auth",
    "aud":"YOUR_CLIENT_ID",
    "exp":"1534928229",
    "nbf":"1534927929",
    "nonce":"6545656756756",
    "iat":"1534927929",
    "sid":"34c64aaa675675670bd54de16670",
    "sub":"85972345",
    "auth_time":"1534901287",
    "idp":"idsrv",
    "name":"john@contoso.com",
    "given_name":"John",
    "family_name":"Smith",
    "role":"[{\"id\":7779,\"cid\":2442,\"rid\":4,\"evm\":false}]",
    "amr":"password"
}

Logging Out

Logging out will require the API Client to redirect the browser to the Logout endpoint passing the ID Token in the id_token_hint querystring parameter as below:

https://accounts.stems.com.au/auth/connect/endsession?id_token_hint=THE_ID_TOKEN

If your API Client needs to clean up any existing session data after logout (e.g. destroying cookies or clearing localStorage variables), Stems Accounts will issue a GET request to the Logout Uri configured for the API Client passing in a sid querystring parameter in the request with the current session id

Security Note

When the Logout Uri receives a request, Stems Accounts will always include a sid query string parameter. You MUST make sure that the sid parameter matches the sid property returned from ID Token Validation response. If the sid parameter doesn't match or it's not present, you should ignore the request