Set up Authentication for Customers

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.

You are reading the SSO docs to login into the Limio Shop and Self-Service. If you are looking at how your employees can access the Limio application via SSO, go to Login options (SSO).

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, Keycloack, Clerk, Firebase and more. If you have a custom-built identity solution, it's recommended to have an OpenID layer to enable SSO.

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 or a self-service page.

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:

Not known to Limio

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

If the customer is known to an external system such as Zuora, it is possible to sync it in Limio on-the-fly. See Configure Zuora to Limio Hot Sync.

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.

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

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

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:

This setup assumes an Amazon Cognito User Pool with OIDC endpoints already configured. See: https://docs.aws.amazon.com/cognito/latest/developerguide/authorization-endpoint.html

Limio uses named instances for environments. We'll refer to {tenant} as the identifier for your Limio application and {tenant-shop} as the identifier for Limio Shop & Self-Service, your customer-facing portal. Append .prod.limio.com for EU hosting or .prod-us.limio.com for US hosting. If unsure, log into Limio and check your browser window.

Provider Name

This is a user-friendly name for your authentication scheme. It could just be 'Default', or the domain of your Limio Shop & Self-Service {tenant-shop}.prod.limio.com , or your custom domain such as dev-subscriptions.company.com . It will be visible to users when they set the authentication on any Limio Page in the Page Builder.

Limio can support multiple identity providers in the same application, so make sure to use a descriptive name. You can always change it later.

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://cognito-idp.us-east-1.amazonaws.com/us-east-1_u11AtClaO

For other services, the Issue Name can 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 for AWS Cognito, but can be found in App Clients → Show Details.

JWKS URI

A JWKS URI is a link to a JSON document listing public keys in the JSON Web Key format. It's used with JSON Web Tokens (JWTs) to verify JWT signatures securely. Limio uses the JWKS URI to access these public keys to check the signature and ensure the JWT is valid and authentic.

For AWS Cognito, it will look like:

https://cognito-idp.eu-central-1.amazonaws.com/eu-central-1_ElEDB2Rnh/.well-known/jwks.json

For other services, the URI could be:

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

Authorization Endpoint*

Authorization Endpoint is important in OAuth 2.0. It's part of the server that lets users log in and approve access to their data. When an app wants to use someone's data, it sends the user to this endpoint. The app includes details like client ID, requested data access, and redirect URI.

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://{tenant}-limio.auth.us-east-1.amazoncognito.com/oauth2/authorize

For other services, it would look like:

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

Logout Endpoint

Logout Endpoint Overview

The Logout Endpoint, or Logout URL/API, is provided by an identity provider to allow users to log out. When a user clicks "Logout" in an app, the app redirects them to this endpoint to properly end their session.

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

https://{tenant}.auth.us-east-1.amazoncognito.com/logout?logout_uri=https://{tenant-shop}.prod.limio.com&

It's also important to note the logout_uri parameter is for the Limio Shop (i.e. your customer-facing portal) and will need to match the one configured in your AWS Cognito instance.

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.

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 part of the OAuth 2.0 system that lets apps get access tokens by exchanging authorization codes or client credentials. There are usually two ways to send client credentials to the token endpoint:

1. Basic Authentication: In this method, the client sends its credentials (client ID and client secret) in the HTTP request's Authorization header using "Basic" authentication. The credentials are encoded in Base64.

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 authenticate the client and get the access token from the token endpoint. The choice between basic authentication and a POST request depends on the OAuth 2.0 server's needs and security.

User Info Endpoint

In OAuth 2.0 and OpenID Connect, the user info endpoint lets applications get data about the logged-in user, like their name and email. This helps apps personalize experiences without storing user data themselves.

This is optional for AWS Cognito. For other services, it could look like:

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

Scope

In OAuth 2.0, a scope defines what access or permissions a client app is asking for when accessing a protected resource. Scopes help limit what the client can do or see. By listing the needed scopes, the app specifies what it needs access to. The available scopes depend on the authorization server or identity provider. During the authorization process, the server shows these requested scopes to the resource owner, who can approve or reject them. For instance, a scope could be:

openid email profile customer_ids address

Limio usually expects at a minimum:

openid profile email

Claims

Identity claims in authentication systems are bits of information about a user. These claims are found in security tokens like JSON Web Tokens (JWTs) or SAML assertions. Limio uses these claims to control access and customize the user experience.

AWS Cognito uses custom attributes for user-defined fields, which can be included as claims in ID tokens. Claims can also be modified dynamically using a pre-token generation Lambda trigger: https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-pre-token-generation.html

Let's take a few examples of custom claims:

Passing Zuora Account ID

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

• Claim-1*: zuora_account_id

• Service: zuora

• Type: account

• Issuer: zuora

This will allow Limio to then run a Hot Sync, and automatically retrieve the Zuora Accounts to display in Self-Service. Learn more at Configure Zuora to Limio Hot Sync.

Passing a Salesforce ID

Passing a User ID

Limio Session

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 24 hours if no value is provided.

Troubleshooting SSO / OpenID Connect

Common issues encountered during SSO setup:

Issue	Cause	Resolution
invalid_request at token endpoint	Limio sends client_id and client_secret in the request body or via Basic Auth depending on your Token Endpoint Type setting.	Verify your IdP accepts the method you selected (Basic vs POST). Switch the setting if your IdP expects the other.
JWT signature verification fails	JWKS URI is missing or incorrect, or the IdP uses a signing algorithm Limio doesn't expect.	Confirm the JWKS URI returns valid keys. Limio supports RS256 signed tokens. Ensure your IdP is configured to sign with RS256.
Issuer mismatch error	The Issuer Name in Limio doesn't match the iss claim in the JWT.	Copy the exact issuer URL from your IdP's .well-known/openid-configuration endpoint. Trailing slashes matter.
Auth redirect loops or blank page	The Provider Name doesn't match the domain of the Limio page, or page hasn't been rebuilt after changing auth settings.	Ensure the Provider Name matches your shop domain. After changing auth settings, rebuild and republish the page, then test in an incognito window.
PKCE-related errors	Your IdP requires PKCE (Proof Key for Code Exchange).	Limio uses the standard Authorization Code flow as a confidential client and does not support PKCE. Configure your IdP to allow the standard Authorization Code flow without PKCE for the Limio client.

After any authentication configuration change, you must rebuild and republish affected pages in the Page Builder. Changes won't take effect until this is done. Always verify in an incognito browser window.

---

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":{
"email": string"[email protected]"
"entitlements":[]
"sub": string"[email protected]"
"address":
{ 
"postal_code":
"region":
"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""
}