Authorization Code Flow

Building Authorization Code Flow libraries for use with Iridium requires a few steps.

• Understanding the Authorization Code Flow Grant Type
• The endpoints used in the Authorization Flow

Understanding the Authorization Code Flow

The authorization code flow is used to get access tokens and refresh tokens. This flow is based on redirection.

1. The resource owner (end-user) visits a third-party client (web application)
2. The resource owner selects the “sign up with Google” button in the client. The user-agent (browser) directs the resource owner to the Google sign-in page.
3. The resource owner (end-user) authenticates and authorizes the authorization server to grant access to the resource owner's information (in this case it could be the email address and profile information) to the third-party client.
4. After the resource owner (end-user) authorizes access, the authorization server redirects the user-agent (browser) back to the original third-party client with an authorization code and typically a state parameter
5. The third-party client requests an access token with the received authorization code and associated redirect URI
6. The authorization authenticates the client, validates the authorization code and the accompanying redirect URI matches the URI provided in step D. If the request is valid the authorization server returns back with an access token and an optional refresh token.

Endpoints used in the Authorization Code Flow

When building clients for Iridium, there are two main RESTful endpoints you need to be familiar with.

1. The authorization endpoint
2. The token endpoint

The external provider authorization endpoint

• Method: POST
• Endpoint: ${serverRoot}/oauth/external/authorize

• Parameters

  • response_type
  • REQUIRED. The value must be code
  • state
  • REQUIRED. This is an opaque value to maintain state between the initial authorization request and the callback.
  • scope
  • REQUIRED. Depending on the provider you are authorizing with will determine the value here. As an example, if you are using GitHub a safe default is user:email
  • redirect_uri
  • REQUIRED. The authorization will redirect the resource owner's user-agent (typically a browser) back to the originating client. This must be an absolute URI.
  • client_id
  • REQUIRED. The client identifier. This is an opaque and unique string generated for the client after registration of it within Iridium.
  • provider
  • REQUIRED. This must be either github or google. This parameter is subject to change in upcoming releases.
  • code_challenge_method
  • REQUIRED. This must be S256
  • code_challenge
  • REQUIRED. The code challenge is derived from the code_verfier (listed below). code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
  • Response:
  • If the request is valid the (end-user) will be redirected to the external identity provider for authorization by the Iridium server.

Creating the code verifier

This is a high-entropy cryptographic random string using the unreserved characters [A-Z], [a-z], [0-9], "-", ".", "_", "~". It is recommended that the output of a suitable random number generator be used to create a 32-octet sequence. The octet sequence is then base64url-encoded to produce a 43-octet URL safe string to use as the code verifier.

The token endpoint

• Method: POST
• Endpoint: ${serverRoot}/oauth/token
• Parameters
• grant_type
  • REQUIRED. This value must be set to authorization_code
• code
  • REQUIRED. This is the authorization code recieved from the Iridium server
• redirect_uri
  • This must match exactly the URI at the above request
• client_id
  • REQUIRED. unless authentication is supplied via HTTP Basic Auth header using the client ID as the username and secret as the password, or by accepting the strings in the post body as client_id and client_secret
• code_verfier
  • REQUIRED. The code_verifier provided at the above request
• Response:
• If the request is successful the response will look similar to the following:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{
  "access_token":"someAccessTokenValue",
  "token_type":"Bearer",
  "expires_in":3600,
  "refresh_token":"SomeRefreshTokenValue",
}