Set up Authentication

Limio Shop and Self-Service offers subscription management with authenticated access. Integrate with identity providers via Limio SSO using OAuth and OpenID Connect for secure authentication.

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

Limio allows users to log in using their current Identity Provider (IdP) through identity federation. This means they can access Limio's secure pages without needing a separate Limio login. Limio supports major IdPs like AWS Cognito, Auth0, Microsoft Entra (formerly Azure), Salesforce, and Firebase. The integration uses OAuth and OpenID Connect, providing a smooth login experience as users directly interact with your company's IdP login page.

This approach avoids identity duplication and enhances the customer experience by using their existing authentication setup.

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.

What is OAuth?

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.

What is OpenID Connect (OIDC)?

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.

Can I authenticate my Limio Commerce app user via SSO?

If you want to federate login into Limio Commerce app, this is managed differently. Go to How to federate your Authentication provider for Limio app users for more details.

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 customer flow in Limio Shop or Self-Service, the Identity will usually work in this way:

1

Customer visits an authenticated Limio page

Customer hits a Limio Page that is marked as Authenticated, usually a checkout.

2

Customer is redirected to login or register

Limio redirects the customer to your Identity Provider

3

Customer registers or authenticate

This is done in your identity provider

4

Customer is redirected to the authenticated Limio page

At this point, Limio will check the sub in the JWT token and either:

Customer is not known to Limio

Create a Limio Identity that maps to your JWT token (defined as a Limio External Identity).

Customer is known to Limio

5

Customer proceeds with the order or change on 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.

6

Customer completes the order or change action

In the next step, Limio processes the order by creating a Limio Order and Event that creates objects in the connected system, such as Zuora and Salesforce. The Zuora and Salesforce Accounts objects will then be linked back to the Limio Customer through Limio Identities.

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 .

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

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

4

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.

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.

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:

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.

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.

How do I know this has worked?

From the user experience: You will need to find to 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"[email protected]"
"entitlements":[]
0 items
"sub":
string"[email protected]"
"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""
}