Single Page Apps

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 three main RESTful endpoints you need to be familiar with.

1. The authorization endpoint
2. The token endpoint
3. The refresh token endpoint

The external provider authorization endpoint

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

Query Params

• Query Parameter	Type	Description
  response_type	string	Required The value must be code
  state	string	Required This is an opaque value to maintain state between the initial authorization request and the callback.
  scope	string	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
  client_id	string	Required The client identifier. This is an opaque and unique string generated for the client after registration of it within Iridium.
  provider	string	Required This must be either github or google. This parameter is subject to change in upcoming releases.
  code_challenge_method	string	Required This must be S256
  code_challenge	string	Required The code challenge is derived from the code_verifier (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

Query Params

Query Parameter	Type	Description
grant_type	string	Required This value must be set to authorization_code
code	string	Required This is the authorization code recieved from the Iridium server
redirect_uri	string	This must match exactly the URI at the above request
client_id	string	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	string	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",
}

The refresh token endpoint

• Method: POST
• Endpoint: ${serverRoot}/oauth/token/refresh

Query Params

Query Parameter	Type	Description
grant_type	string	Required This value must be set to refresh_token
refresh_token	string	Required The refresh token
client_id	string	Required The client identifier. This is an opaque and unique string generated for the client after registration of it within Iridium.
### 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",
}

The logout endpoint

• Method: DELETE
• Endpoint: ${serverRoot}/application/${clientId}/tokens

Path Variables

Path Variable	Type	Description
client_id	string	Required The client identifier. This is an opaque and unique string generated for the client after registration of it within Iridium.

Headers

Header	Value	Description
Authorization	Bearer	Required The users bearer token
### Response:
* If the request is successful the response will look similar to the following:

HTTP/1.1 204 No Content

An example on how invoke is below:

$ curl --location --request DELETE 'http://localhost:8381/applications/localRunIdChangeForProduction/tokens' \
--header 'Authorization: Bearer {SomeTokenValue}'