How to federate your Authentication provider via OAuth and OpenID with Limio

Within your Limio Shop and Self-Service, customers have the ability to log in to their accounts, view their subscriptions and edit their details. To do so, customers must authenticate.

Limio federates identity with your existing authentication provider (identity federation or federated identity). Identity federation is a mechanism that allows users to access Limio authenticated pages via your current Identity Provider (IdP), linking Limio's identity to the identity of your Identity Provider. All major IdP such as AWS Cognito, Auth0, Microsoft Entra (formely Azure), Salesforce, and more.

In this document, we discussed how to federate identity via OAuth and OpenID Connect. 

• OAuth (Open Authorization) is primarily the authorization framework. It allows the company to grant permission to the Limio application (client) to access protected resources on their behalf. This is the first item to setup.
• OpenID Connect (OIDC) is built on top of OAuth 2.0 and adds an authentication layer. It provides a standardized way for Limio to verify the identity of the end-user and obtain user profile information. OIDC is focused on authentication, enabling clients to authenticate users, receive identity claims, and establish trust in the identity information provided by an identity provider (IdP). This is the second item to setup.

From an end-customer perspective, this is seamless and they will only visually interact with your company's Identity Provider. Any styling on the registration or login page would therefore be done in your authentication system, similar to how they would access your product(s). In other words, you do not need a separate Limio login to access self-service. This results in a better, more seamless customer experience and avoid issues stemming from duplicative identities across different data stores.

This page covers:

• How does Limio Identity work in practice
• Set up OAuth & OpenID
• OpenId Value Definitions (with example from AWS Cognito)
• OpenId example for Azure AD B2C

We also have other articles for specific providers:

• OpenId example for Auth0
• OpenId example for Okta

Setting up Identity Federation requires some pre-existing knowledge around Identity and security, and this document is aimed at Architect, DevOps Engineer, or IT Engineers. 

Overview

How does Limio Identity work in practice

Limio uses a standard identifier, such as sub (subject), to determine a user’s identity. In the JSON Web Token (JWT) standard, the sub is a string that identifies the principal that is the subject of the JWT. This is usually the user and may look like "sub": "1234567890". Limio will create a Limio Identity that maps to this sub.

From a new customer flow, the Identity will usually work in this way:

1. Customer hits a Limio Page that is marked as Authenticated, usually a checkout.
2. Limio redirects the customer to your Identity Provider
3. Customer registers or authenticate in your Identity Provider
4. The Customer is then redirected to the authenticated Limio Page, for example the checkout. 
   • At this point, Limio will create a Limio Identity that maps to your JWT token (defined as a Limio External Identity). 
5. The Customer proceeds with the order in the authenticated Limio Page.
   • At the time of purchase, Limio creates first objects like Limio Subscription and Limio Customer, which are tied to a Limio Identity.
   • In the next step, Limio processes the order by creating a Zuora Order that provisions both a Zuora Account and a Zuora Subscription. The Zuora Account is then linked back to the Limio Customer through a Zuora Account Identity.
   • Optionally, a Salesforce Account Identity and Salesforce Contact Identity can also be related to the Customer.

Below is an example of the Limio Identities stored on a Limio Customer:

From an existing customer flow, the Identity will usually work this way:

1. The Customer hits a Limio Page that is marked as Authenticated, for example a My Account or Switch (Upgrade/Downgrade) Page.
2. Limio checks the sub in the JWT token, finds the corresponding Limio Identity, and identifies the relevant Limio Subscription(s) to display in My Account or whether the customer is authorised to access the specific Switch Page.

A couple of points:

• Limio will usually expect the sub to be the primary identifier. However, it is possible to use Claims to define alternative identifier. See Claims in this document for more information.
• It is possible to append more External Identity to a Limio Customer, for example to facilitate multiple B2B users manipulating Limio Subscription(s). Learn more here. 

Set up OAuth & OpenID

Adding an Authentication Provider via OAuth and OpenID with Limio

1. Set the authentication type to OAuth in General Settings → Site Security

   

2. Now you’re ready to add the Authentication Provider, first select Authentication Providers on the left side panel. You should see this view:

3. Then click on the OpenID Connect button to add a new provider. You will be presented with a modal like this.

4. The details you need to enter are marked with an asterisk. Enter the data from your authentication provider.

OpenId Value Definitions (with example from AWS Cognito)

In this example we will specifically be going through adding AWS Cognito to OpenID, however, the process will work for any OAuth provider:

Provider Name

The name of the Limio Shop e.g. company-dev-shop.prod.limio.com or a custom domain such as dev-subscriptions.company.com

Issuer Name

The issuer name, also known as the Issuer Identifier, is a unique identifier used to identify the issuer or entity that issued a security token, such as a JSON Web Token (JWT) or a SAML assertion. It provides a means for the recipient of the token to validate the token's authenticity and determine the authority responsible for its issuance. The issuer name typically takes the form of a URL or a string identifier that uniquely identifies the issuing entity. It could be the URL of the identity provider or authorization server, or it could be a custom identifier specific to the issuer.

For example, it could be

https://server.dev.company.com/auth-server

Client ID

This can be found in the AWS Console. Look in Cognito → Relevant user pool → App Client Settings. The ID is labelled and centrally placed just under the app client and will take the form of a series of letters and integers.

Client Secret

This isn’t necessary to work, but can be found in App Clients → Show Details

JWKS URI

A JWKS URI (JSON Web Key Set URI) is a Uniform Resource Identifier that points to a JSON document containing a set of public keys in the JSON Web Key (JWK) format. It is commonly used in the context of JSON Web Tokens (JWTs) for securely verifying the signatures of JWTs. The JWKS URI is used by Limio to obtain the necessary public keys to verify the authenticity and integrity of the JWT issued by an identity provider or authorization server. By retrieving the keys from the JWKS URI, Limio can validate the JWT's signature and ensure its validity.

For example, the URI could be:

 https://server.dev.company.com/auth-server/oauth2/jwks 

Authorization Endpoint*

The Authorization Endpoint is a critical component in the OAuth 2.0 protocol. It is an endpoint provided by the authorization server that handles user authentication and consent for granting access to protected resources on behalf of the user. When a client application wants to access protected resources on behalf of a user, it initiates the OAuth 2.0 flow by redirecting the user to the Authorization Endpoint. The client includes specific parameters in the request, such as the client ID, requested scopes, redirect URI, and other optional parameters.

To find the AWS Cognito Domain navigate to Domain Name in Cognito. You will then need to append to /oauth2/authorize to the end of it. It will look like:

https://server.dev.company.com/auth-server/oauth2/authorize

Logout Endpoint

The Logout Endpoint, also known as the Logout URL or Logout API, is an endpoint provided by an identity provider or authentication system that allows users to log out or terminate their authenticated session. When a user initiates a logout action, such as clicking a "Logout" button in an application, the application redirects the user to the Logout Endpoint provided by the identity provider. The Logout Endpoint performs a series of actions to end the user's session and ensure proper logout functionality:

If you are using AWS Cognito as an authentication provider, it will look like:

https://coal01-limio.auth.eu-central-1.amazoncognito.com/logout?logout_uri=https://coalfire-dev-shop.prod.limio.com&

It's also important to note the logout_uri parameter will need to match the one configured in AWS Cognito.

Token Endpoint*

The Token Endpoint is an endpoint provided by the authorization server where client applications can exchange authorization grants, such as authorization codes or client credentials, for access tokens.

When a client application needs to access protected resources on behalf of a user, it first obtains an authorization grant by redirecting the user to the Authorization Endpoint. After the user authorizes the access, the authorization server issues an authorization code to the client.

The client then exchanges this authorization code with the Token Endpoint to obtain an access token. The access token is a credential that represents the client's authorization to access the requested resources. The client may also receive a refresh token, which can be used to obtain a new access token when the current one expires.

In AWS Cognito, it will be the domain with /oauth2/token appended to it. It will look like

https://coal01-limio.auth.eu-central-1.amazoncognito.com/oauth2/token.

Token Endpoint Type*

The token endpoint is a part of the OAuth 2.0 framework that allows clients (applications) to exchange authorization codes or client credentials for access tokens. When it comes to the method used to send the client credentials to the token endpoint, there are typically two options:

1. Basic Authentication: In this method, the client includes its credentials (client ID and client secret) in the Authorization header of the HTTP request using the "Basic" authentication scheme. The credentials are encoded in Base64 format. 
2. POST Request: In this method, the client includes its credentials (client ID and client secret) in the body of the POST request as URL-encoded parameters. The parameters are typically named "client_id" and "client_secret" respectively.

Both methods serve the purpose of authenticating the client and obtaining the access token from the token endpoint. The choice between basic authentication and POST request depends on the specific implementation and security requirements of the OAuth 2.0 server.

User Info Endpoint

The user info endpoint is an endpoint in the OAuth 2.0 and OpenID Connect protocols that allows clients (applications) to obtain information about the authenticated user. It provides a standardized way to fetch the user's profile data, such as their name, email address, profile picture, or other relevant attributes.

The user info endpoint enables clients to retrieve user-specific details without directly accessing or storing user data. It promotes interoperability and allows applications to provide personalized experiences based on the user's profile information obtained from the identity provider or authorization server. For example, it could look like:

https://example-identity-provider.com/userinfo

Scope

In the context of authorization protocols like OAuth 2.0, a scope is a parameter that defines the level of access or permissions requested by a client application when making a request to access a protected resource. Scopes are used to limit and control the access rights granted to the client.

Scopes provide a way for the company to authorize specific actions or data access requested by Limio. By specifying the desired scopes in the authorization request, the client indicates the extent of access it needs to perform its intended operations.

The specific scopes available and their meaning depend on the authorization server or identity provider being used. The server typically presents the requested scopes to the resource owner during the authorization process, and the resource owner can grant or deny access based on the scope requests. For example, scope could be:

openid email profile customer_ids address

Claims

In the context of authentication and authorization systems, identity claims refer to the pieces of information or attributes associated with a user's identity. These claims provide relevant details about the user and are typically included in security tokens such as JSON Web Tokens (JWTs) or SAML assertions. These claims are then used by Limio to make access control decisions or personalise the user experience.

Let's take a few examples of custom claims:

Passing a Salesforce ID as a Custom Claim

If you wanted to automatically provide the Salesforce Account ID of the User that is defined as crm_id in your JWT token, go to OpenID Connect > Identity Claims section and add the following Claim:

• Claim: crm_id (This value must match the custom claims set in your Identity Provider)
• Service: salesforce (This identifies the service or system from which the claim originates)
• Type: account (This indicates the type of entity being claimed, such as an account or user)
• Issuer: salesforce

Passing a User ID as a Custom Claim

If you wanted to automatically provide a User ID of an application that is defined as user_id in your JWT token, go to OpenID Connect > Identity Claims section and add the following:

• Claim: user_id (This value must match the custom claims set in your Identity Provider)
• Service: user (This identifies the service or system from which the claim originates)
• Type: id (This indicates the type of entity being claimed, such as an account or user)
• Issuer: user

Limio Session

From release 104, the session length can be set in the Limio Session section of the provider settings. This controls the duration in which a user session remains active in Limio before requiring re-authentication. It defaults to 1 hour if no value is provided.

 

OpenID Configuration for Azure AD B2C

Populate the following value from your Azure instance:

Provider Name
The name of the Limio Shop, e.g., test-dev-shop.prod.limio.com.

Issuer Name
The Issuer URL:
https://{tenant}b2csandbox.b2clogin.com/{tenant}b2csandbox.onmicrosoft.com/v2.0/

Client ID
Retrieve this from the Azure AD B2C Portal. See Microsoft Documentation.

Client Secret
Obtain this from the Azure AD B2C Portal. See Microsoft Documentation.

JWKS URI
This provides the JSON Web Key Set (JWKS) for token verification, e.g.: https://{tenant}b2csandbox.b2clogin.com/{tenant}b2csandbox.onmicrosoft.com/B2C_1A_SIGNUP_SIGNIN/discovery/v2.0/keys

Authorization Endpoint
The URL for user authorisation, e.g.: https://{tenant}b2csandbox.b2clogin.com/{tenant}b2csandbox.onmicrosoft.com/B2C_1A_SIGNUP_SIGNIN/oauth2/v2.0/authorize

Token Endpoint
The endpoint for obtaining tokens, e.g.: https://{tenant}b2csandbox.b2clogin.com/{tenant}b2csandbox.onmicrosoft.com/B2C_1A_SIGNUP_SIGNIN/oauth2/v2.0/token

Logout Endpoint
The endpoint for user logout, e.g.: https://{tenant}b2csandbox.b2clogin.com/{tenant}b2csandbox.onmicrosoft.com/B2C_1A_SIGNUP_SIGNIN/oauth2/v2.0/logout

Token Endpoint Type
Typically set to Basic.

Scope
Define the required scopes in the Azure AD B2C Portal, such as openid, profile, and email.

How do I know this has worked?

From the user experience: You will need to find to set the authentication that you create on a page in Limio (for example the checkout page), rebuild and republish it.

Then, access a pricing page or go through a purchase flow. When you access the checkout, you should now be redirected to your authentication provider. Complete the order via the newly authenticated checkout and then go in the Limio application.

In Limio: After the order has been taken, navigate to Limio Subscriptions > Limio Customer > Identity and click on the Limio identity (Service: Limio).

Then scroll down to find the identity that has @limio/external-id.

You will then see the full identity token received from your Identity Provider, for example:

"root":{

15 items

"email":

string"[e-mail]"

 

"entitlements":[]

0 items

"sub":

string"[e-mail]"

 

"address":{

3 items

"postal_code":

NULL

"region":

NULL

"country":

string"CA"

}

"email_verified":

boolfalse

"tgam_id":

int114517357

"iss":

string"https://domain.com/auth-server"

"given_name":

string""

"aud":

string"limio"

"isValidated":

booltrue

"crm_id":

string"001Sv00000GVVcoIAH"

"azp":

string"limio"

"exp":

int1738168134

"iat":

int1738166334

"family_name":

string""

}