Application SSO | JSON web token

JSON web token (JWT) is a technique that can be used for single sign-on (SSO) between a custom application (such as your product) and another application. In this case JWT can be used for SSO to your Aha! Builder application so that users of your product can log in using the same credentials.

• Configure JWT SSO for your application

• The JWT single sign-on process

• Build the JWT response

Configure JWT SSO for your application

1. From your application in Aha! Builder, navigate to Configuration -> Authentication.

2. Next to Custom SSO (SAML, JWT), select Add provider. Then select JWT.

3. Add a Name for the SSO configuration and select Create provider.

4. The JSON Web Token configuration will display. Add a Remote login URL. This is the URL that users should be redirected to in order to authenticate before redirecting back to your application. Then copy the Callback URL. You will use this when building the JWT response.

   1. Optional: Add a Remote logout URLl if you want to send your users to a specific URL when they log out of your application.

5. Click Save to enable the configuration.

Top

The JWT single sign-on process

When a user authenticates using SSO they go through the following process:

1. The user navigates to your application login page e.g. https://prod-xyz12345.use1.aha.host, or if you are using a custom domain, your CNAME, e.g. https://application.yourcompany.com.

2. Your application recognizes that it is configured to use JWT.

3. The user's browser is redirected to the third part application using the Remote login URL that you configured on the JSON Web Token (JWT) configuration screen.

4. Your product recognizes that it has received a JWT authentication request.

5. Your product authenticates the user.

6. Your product builds a JWT response and redirects the user back to your application using the Callback URL in your SSO configuration, including the JWT response, like the following URL: https://yoursubdomain.aha.io/api/core/auth_ui/jwt/providers/01234567890/callback?jwt=#{payload}&state=#{state}.

7. Your application validates the JWT response. If this user has never accessed the application before a new user record is created.

8. The user is granted access to your application.

It is possible to start the process at step 5 without the user visiting your application first.

Top

Build the JWT response

When it receives a JWT authentication request your application must wait for a JWT response. The response should include a HS256-encoded token containing these fields:

• iat - The integer time the response was created in seconds since the Unix epoch.

• jti - A randomly created token that uniquely identifies this response.

• first_name - the first name of the user that was authenticated.

• last_name - the last name of the user that was authenticated.

• email - the email address of the user that was authenticated. The email address is used to uniquely identify the user within your application.

• sub - A unique identifier for the user, different from their email. This is optional but recommended.

Here is sample Ruby code to generate a response:

iat = Time.now.utc.to_i
jti = "#{iat}/#{rand(36**64).to_s(36)}"
payload = JWT.encode(
  {
    iat: iat,
    jti: jti,
    first_name: "John",
    last_name: "Doe",
    email: "john.doe@aha.io",
  }, 
  secret_key)

Here is the format of a URL used for login. This URL can be copied from the Callback URL in your SSO configuration:

"https://yoursubdomain.aha.io/api/core/auth_ui/jwt/providers/01234567890/callback?jwt=#{payload}&state=#{state}"

Here is an example URL:

https://yoursubdomain.aha.io/api/core/auth_ui/jwt/providers/01234567890/callback

Your URL will generate a JWT that looks like this:

{ "iat": 158258345634, "jti": "1234567890abcdefg", "first_name": "John", "last_name": "Doe", "email": "john.doe@aha.io" }

If the request contains state query parameter then the value of that parameter should also be included in the redirect:

"https://#{subdomain}.aha.io/api/core/auth_ui/jwt/providers/callback/01234567890/#{payload}&state=#{state}"

Top