Superloop Connect - Authentication

Introduction

Connect API uses OAuth 2.0 OIDC for authentication. Specifically the Private Key JWT (private_key_jwt) authentication method is used. In this authentication mechanism there is a registered public key for the client held by the authorization server. A client signs a Json Web Token (JWT) using the matching private key. The client then makes a https request to the token endpoint where the JWT is exchanged for an access token. The JWT must contain the claim values as specified in Creating a signed JWT. Once the JWT is created and signed it can be exchanged for an access token as detailed in Exchanging the signed JWT for an Access Token.

Details on the private_key_jwt authentication method can be found here: private_key_jwt

Relevant RFCs

Prerequisites

You have obtained the private and public key for your client from Superloop.
You have obtained your client name (client_name) from Superloop.
You know the token endpoint is https://sso.superloop.com/auth/realms/superloop/protocol/openid-connect/token

Obtaining an Access Token

Obtaining an access token is a two step process that involves:

Creating a signed JWT
Exchanging the signed JWT for an Access Token

Creating a signed JWT

Create a JWT that conforms to the following format:

JWT Header

Table 1. JWT claims that need to be provided in the Header of the signed JWT
Field	Value	Example	Detail
alg	RS256	RS256	Specifies the the SHA-256 hash algorithm ("RS256"). You must encode the JWT using this algorithm.
kid	<public_key_kid>	u_noihscmXSbckXAxuopC4SeD5lF68NoWqNs0ZUTWdA	The key identifier from the issued public key.

JWT Header Example

{
  "alg": "RS256",
  "kid": "u_noihscmXSbckXAxuopC4SeD5lF68NoWqNs0ZUTWdA"
}

JWT Payload

Table 2. JWT claims that need to be provided in the Payload of the signed JWT
Field	Value	Example	Detail
jti	GUID	302624bd-5d85-4872-9495-3010bbcec6da	Provides a unique identifier for the JWT. For example a guid.
exp	NumericDate as per JSON Web Token (JWT)	1617012693	The expiration time on or after which the JWT MUST NOT be accepted for processing.
nbf	NumericDate as per JSON Web Token (JWT)	1616982693	The time before which the JWT MUST NOT be accepted for processing.
iat	NumericDate as per JSON Web Token (JWT)	1616982693	The time at which the JWT was issued.
iss	<client_name>	sl-360-vip	Identifies the principal that issued the JWT.
aud	https://sso.superloop.com/auth/realms/superloop	https://sso.superloop.com/auth/realms/superloop	Identifies the principal that issued the JWT.
sub	<client_name>	sl-360-vip	The principal that is the subject of the JWT.

JWT Payload Example

{
  "jti": "302624bd-5d85-4872-9495-3010bbcec6da",
  "exp": 1617012693,
  "nbf": 1616982693,
  "iat": 1616982693,
  "iss": "slc-360-vip",
  "aud": "https://sso.superloop.com/auth/realms/superloop",
  "sub": "slc-360-vip"
}

Once created the JWT needs to be signed using the issued private key.

Note: JWTs are single use.

Exchanging the signed JWT for an Access Token

Perform a POST request on the token endpoint with the signed JWT to exchange it for an access token. The following specific parameter values and encodings need to be set:

Table 3. Parameters Values for the HTTPS request
Parameter	Value	Example
grant_type	client_credentials	client_credentials
client_id	<client_name>	slc-360-vip
client_assertion_type	urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer	urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
client_assertion	<signed_jwt_token>	eyJhbGciOiJSUzI1NiIsImtp …

Request to exchange a singed JWT for an access token

curl -k -X POST https://sso.superloop.com/auth/realms/superloop/protocol/openid-connect/token \
-d "grant_type=client_credentials" \
-d "client_id=slc-360-vip" \
-d "client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer" \
-d "client_assertion=eyJhbGciOiJSUzI1NiIsImtpZ ..."

If the request is successful a response similar to below will be returned

Response

{
   "access_token":"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJYdFEtWkpQYnZ0VzNYTnpwNWY2Sk5IRml5RVF6NmUwcmxpOEROUHg3Z0lnIn0.eyJqdGkiOiIyZmExYjI2ZS00NDFkLTRjNjYtOWYwZi0xMGM3YjI2YzFmNjQiLCJleHAiOjE2NzQ2OTk1MDksIm5iZiI6MCwiaWF0IjoxNjExNjI3NTA5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvc3VwZXJsb29wIiwic3ViIjoiY2EwY2U2NmEtNDA4Yy00YjNhLWFhNzMtMTE5YjQ5MjM0NmJjIiwidHlwIjoiQmVhcmVyIiwiYXpwIjoicG9ydGFsLWFwaSIsImF1dGhfdGltZSI6MCwic2Vzc2lvbl9zdGF0ZSI6IjUxMDEyYWQxLWZlMzktNDI2OS1iMjUwLTkyMWJiMWM5Yzg5YSIsImFjciI6IjEiLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsib25uZXRfYXBpX3ZpZXdfZmVhdHVyZXMiXX0sInNjb3BlIjoiIiwiY2xpZW50SG9zdCI6IjEyNy4wLjAuMSIsImNsaWVudElkIjoicG9ydGFsLWFwaSIsInVzZXJJZCI6IjIwNzQiLCJjbGllbnRBZGRyZXNzIjoiMTI3LjAuMC4xIiwiYXBwcyI6InBvcnRhbC1hcGksb25uZW50LWFwaSJ9.bSxTHnjn0E_8hWgs1LncLBSRbiQb-SlCJlv2OYAgl8MxrLPh_Vdd0Ql6S6l4le9bmq6l5Xre16M2T2IKgmc-cPFgXEhGALSQag0MVtFsdyG0ddaMvdIA-ObyGADKveGxlpiYoepHe-jMl2pnsj0zNlAZuBT_drj1mMdF5x68drgQIu6A7FCJGA9kulD-Z3f7RnIsBXBa0JlXSKuLiacp7QspJJ21r3gvEIEwlSdNUQ0XRYrZGKt9xTmiclop3nmMCCQVmvz1NIP7K6GydI00fNrkoPnR8MGDFYQ2M4Y6ib5f3Ej5GXdsQB3-Xtqv61sayutG_1TbgQI14LLGePqjiQ",
   "expires_in":300,
   "refresh_expires_in":0,
   "token_type":"Bearer",
   "not-before-policy":0,
   "scope":""
}

The access_token field contains the access token which is passed in the Authorization header when making requests to the Connect API.

Refresh Token

Refresh tokens are not applicable for the client_credentials grant type.

Client Libraries

There are many libraries available for creating signed JWTs. Have a look at jwt.io for some of the more popular ones (scroll down the page). You should also be able to use jwt.io to manually create and sign JWTs.