JWT with Amazon Cognito

We utilize Amazon Cognito as our Identity Provider (IdP). An IdP is a service responsible for authenticating users through their usernames and passwords. In the context of Single-Sign-On (SSO), user identification (ID) information 🪪 is securely transferred—or federated—from your corporate system to Cognito and then to our system. This federation process ensures that we do not directly access any sensitive data.

We use Cognito to keep your credentials as secure 🔐 as possible. Our system never "touches" 👈 or "sees" 👀 your password. We do know your username (email address) and a cognito-generated ID, which is how we link your account to analysis executions, files, etc.

During your onboarding process, you should have received a username and password which was generated by Amazon Cognito. Those two values along with a Client Id (found in your User Settings online) will allow you programmatic access to the Aplos NCA Analysis SaaS system.

Tip

Don't worry, you can't do anything bad, and everything you do is locked to your user identity, tenancy and account.

SSO Single-Sign-On Support

As mentioned in the intro, Cognito can be integrated with your federated IdP Single-Sign-On SSO. If you require SSO please reach out to our support team.

Note

Using SSO will require an a team or enterprise account and some lead time for set up. You can always start without SSO and upgrade later.

Obtaining a JWT

JWTs can be obtained via using standard username/password flow (ALLOW_USER_PASSWORD_AUTH), Secure Remote Password flow (ALLOW_USER_SRP_AUTH) or via a client id and client secret which is typically used for automated solutions.

Whichever method you use it's important to keep these values confidential.

Connecting to Amazon Cognito

No matter what tool you use (Java, Python, c#, R, Ruby, PHP, curl, etc), connections to Amazon Cognito are essentially HTTPS calls.

To keep it simple here is an example using curl in shell command. If you're not used to using shell commands or curl, that's ok. We'll try to make it as straightforward as possible and explain it along the way.

We also have examples using Python, R and SAS.

When you look at the following script, notice there are only three values that you need to provide, for the rest of the script you can use "as-is".

Name	Value	Description
COGNITO_USER_NAME	Your username	your email address
COGNITO_PASSWORD	Your password	provided during onboarding
COGNITO_CLIENT_ID	Your cognito client id	Available in your profile settings

Tip

curl is a shell command that allows you to make web (http/https) requests in the command line. It's simple and easy to use.

In the example below, the payload refers to the body of an HTTPS request. It is included in the body/data of the web request, which ensures that it is transmitted securely and encrypted. The request uses HTTPS which automatically handles the encryption and decryption of data, similar to how your browser secures data when you're online.

The header information required here, is supplied by AWS and you can find more detail in their documentation.

The flow of this process extracts environment variables into local variables called: username, password and client_id and then adds them to the payload and makes a curl https request to get retrieve your token. The outputs it into your shell.

Shell Script Example

Given the code above you and if you saved it in a file named amazon-cognito-jwt.sh, you can execute the following:

The Response

The output won't be as clean as the output below, but you'll get back something like the following:

Note

This was a real response from a temp account I created. I removed the RefreshToken for safety as it's a long-lived token. We're serious about security so that account has also been disabled and is scheduled for destruction.

Here's a brief description of each field typically returned in a response from Amazon Cognito when dealing with tokens:

1. AccessToken:

   • The access token is part of the credentials used to access authorized resources. It is issued by the authorization server and allows the API to make requests on behalf of the user who authorized the app. This token typically has a limited lifespan and scope.

2. ExpiresIn:

   • This field indicates the number of seconds remaining until the token expires. Once expired, the token is no longer valid, and a new one must be obtained, typically using the refresh token.

3. IdToken: 👈 This is JWT you will pass in all of your API requests.

   • The ID token is a JSON Web Token (JWT) that contains claims about the authentication of the user. It often includes user profile information (like the user's ID, username, email, and so forth) which the client can use to identify the user.

4. RefreshToken:

   • The refresh token is used to obtain a new access or ID token after the current one expires. This token has a longer lifespan than the access token and is meant to be stored securely by the client.

5. TokenType:

   • This field specifies the type of token that is issued. Typically, this field will have the value "Bearer", which indicates that the token is a bearer token, meaning that any party in possession of this token can use it to access the resources it grants access to, without further identification.

Viewing the Contents of the IdToken

When the IdToken is decoded it looks like the following.

If I can view the token, how is it secure?

JSON Web Tokes (JWTs), which are just base64-encoded are easily read. However, altering the contents of the token is not effective due to the security measures in place:

1. Digital Signature:

   • Each ID token is digitally signed by the issuer (in this case, Amazon Cognito) using a cryptographic algorithm. When the token is issued, it includes a signature that is generated from the token content and a secret key that only the issuer possesses.

2. Verification of Integrity:

   • When a service or server receives an ID token, it does not just decode it; it also verifies the token’s signature. This is done by using the issuer's public key to ensure that the signature is valid. If someone were to alter the contents of the ID token (like changing user permissions or identity), this would invalidate the signature.

3. Security Protocols:

   • Altering the signature itself requires access to the private key used by the authenticating server, which is securely held by the issuer (Amazon Cognito) and not accessible to users or any third parties. Without this key, a valid signature cannot be recreated after altering the token.

While the contents of an ID token can be viewed by anyone, any modifications to the token would prevent it from being verified properly by services expecting a valid token. This verification failure would lead to the token being rejected, thereby safeguarding the system from unauthorized access or alterations.

Next Steps

Now that you have a token, you can make calls to the Aplos NCA SaaS system. This is of course assuming your account is valid ✅, your subscription is active 🎉 and finally, you have the correct permissions 🔓 (whew) 🥵 : you can make calls against our APIs 🚀.