Implementing Single Sign On (SSO) with Frontegg APIs

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

https://[your-frontegg-domain]/identity/resources/auth/v2/user/sso/prelogin

{
address: string(the redirect address),
idpType: enum(oidc/saml - the type of the authentication protocol)
}

https://[your-frontegg-domain]/auth/saml/callback

{
"RelayState": string (the state that Frontegg provided to the IDP in the request to the IDP),
"SAMLResponse": string(the authenticated entity data)
}

{
 "code": string (The code returned from the IDP),
 "state": string (The state returned from the IDP)
}

`https://[your-frontegg-domain]/identity/resources/auth/v2/user/oidc/postlogin` request 

{
"code": string (The code returned from the IDP),
"redirectUri":"http://your-application-url/account/oidc/callback",
"RelayState":"string (The state returned from the IDP)"}

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}