This article describes all the steps for creating an SSO connection with Frontegg as Service Provider (SP) and implementing SAML / OIDC SSO via Frontegg APIs.
Enable and Configure SAML / OIDC in the Frontegg Portal
1. Make sure SAML / OIDC is enabled in the Frontegg Builder:
2. In your Frontegg testing environment, go to Authentication → SSO → SAML / OIDC and configure the Service Provider side by following the steps in this guide for SAML or this for OIDC.
Since you are implementing the SSO flow via APIs only, there is no need to use `account/saml/callback` OR `/account/oidc/callback` in the Redirect Url. You can redirect to the client route of your choice that you are implementing in the code.
3. Configure your SAML / OIDC application in the Identity Provider. You can follow this guide for the Okta SAML application as an example, and this guide for OIDC.
Add an SSO connection on your test account (tenant) in the environment.
Via API:
Get your Environment vendor token by following these instructions and use the below endpoints to create an SSO connection, assign a domain to the connection and assign default + groups (optional) roles.
1. Add the SSO Configuration - with the details you have received from your IDP, after creating a SAML / OIDC app.
2. Add the SSO Domain - Frontegg identifies the existence of an SSO connection by the domain of the user's email. This should be the organization's domain.
3. Validate the domain - Generally, we will generate TXT records after the domain is inserted and the end user would need to add these to their DNS. Then you can go ahead and validate that domain via this endpoint. However, if you prefer avoiding this process, you can force domain validation by using this endpoint.
**If you'd like to implement domain validation via DNS records, this is the format that you should provide your users with:
Record Name - _saml-domain-challenge.[domain]
Value - "xxxx" (when you create an SSO config you get in the response)
4. Set a default role for all SSO users
5. Map an SSO IDP group to a Frontegg role (optional).
Via Frontegg Portal:
Go to an environment → Accounts → a specific account → SSO Configurations
Implement Authentication Flow
1. Send a POST request with the user's email to verify on Frontegg that the email domain is registered for SSO:
https://[your-frontegg-domain]/identity/resources/auth/v2/user/sso/prelogin
The response will either return the IDP redirect:
{
address: string(the redirect address),
idpType: enum(oidc/saml - the type of the authentication protocol)
}
Or 404 if an SSO connection with that domain isn't found.
2. After the user is authenticated with the IDP, you will need to send a POST request to Frontegg.
The body and endpoints change per protocol type (SAML / OIDC)
SAML:
Once the user is authenticated the IDP will redirect the user to the `ACS URL` using POST method and provide a JSON with the authentication information in the request body, as described below.
A POST request is sent automatically to:
https://[your-frontegg-domain]/auth/saml/callback
With the below payload:
{
"RelayState": string (the state that Frontegg provided to the IDP in the request to the IDP),
"SAMLResponse": string(the authenticated entity data)
}
OIDC:
Same as SAML, the IDP will redirect the user to the redirect URL configured at Frontegg - `/account/oidc/callback`, it will be a GET request with the following query params :
{
"code": string (The code returned from the IDP),
"state": string (The state returned from the IDP)
}
A POST request to the below endpoint will be sent:
`https://[your-frontegg-domain]/identity/resources/auth/v2/user/oidc/postlogin` request
With the below payload:
{
"code": string (The code returned from the IDP),
"redirectUri":"http://your-application-url/account/oidc/callback",
"RelayState":"string (The state returned from the IDP)"}
3. The `/postlogin` route for OIDC or `/auth/saml/callback` for SAML, will return a refresh token (refresh cookie). `/auth/saml/callback` automatically redirects to `http://your-application-url/account/saml/callback`. In order to prevent the redirect and catch the refresh token that is returned in the response cookies, you will need to set maximum redirects to 0.
4. Include cookies and send a `/refresh` request to get the user's JWT and a new refresh token
curl --location --request POST 'https://[your-frontegg-domain]/identity/resources/auth/v1/user/token/refresh' \
--header 'Cookie: fe_refresh_[client-id]=refresh-token' \
--data-raw ''
The client-id format should be {12}-{4}-{4}-{12}