Sign in to the console with SSO
This guide sets up single sign-on (SSO) for the Airgate console. At the end, administrators select Sign in with SSO, enter their work email, sign in at your identity provider (IdP) and land in the console. Their console account is created at the first sign-in.
This is for administrator sign-in to the console only. For users signing in to the network, see Entra ID, Okta or Google Workspace.
Before you begin
Section titled “Before you begin”- The console’s public address, set as
PUBLIC_URL(for examplehttps://nac.contoso.com). The addresses you register at the IdP are built from it. Most IdPs accept onlyhttps(plainhttponly forlocalhost). - A local Tenant Administrator that keeps signing in with a password, as a break-glass account in case the IdP is unavailable or misconfigured.
- Administrator rights at the IdP to add an application.
- In Airgate: the Tenant Administrator role (needs admin write access).
SAML or OpenID Connect? Both work. SAML is common for Entra ID enterprise apps, Google Workspace and ADFS; OpenID Connect is simpler for Okta and Entra ID app registrations.
Step 1: Start the provider in Airgate
Section titled “Step 1: Start the provider in Airgate”-
Open Settings › Single sign-on.
-
Select SAML 2.0 or OpenID Connect.
-
Under Provider, enter:
- Name, for example
Contoso Entra ID. - Email domains: type
contoso.comand press Enter. Sign-ins for these domains go to this provider, and only these domains can sign in through it. A domain belongs to one provider only. - Enabled (shown on the sign-in page): leave on, or turn on after the test.
- Name, for example
-
Keep the dialog open. The right column, Register Airgate at your IdP, already shows the addresses to register, before anything is saved:
- SAML: Identifier (Entity ID), Reply URL (Assertion Consumer Service URL) and Sign on URL.
- OpenID Connect: Redirect URI (Web) and Home page URL (optional, branding only).
These addresses stay the same when you select Add provider. If you cancel, they are discarded and the next attempt gets new ones.
Step 2: Register Airgate at the IdP
Section titled “Step 2: Register Airgate at the IdP”Microsoft Entra ID with SAML
Section titled “Microsoft Entra ID with SAML”- In the Microsoft Entra admin center, open Entra ID › Enterprise apps (older layouts: Identity › Applications › Enterprise applications) and select New application › Create your own application.
- Enter
Airgate console, choose Integrate any other application you don’t find in the gallery (Non-gallery) and select Create. - Open Single sign-on and choose SAML.
- In Basic SAML Configuration, select Edit and enter the Identifier (Entity ID) and Reply URL (Assertion Consumer Service URL) from Airgate. Optionally set Sign on URL to the one Airgate shows. Save.
- Under SAML Certificates, copy the App Federation Metadata Url.
- Open Properties, set Assignment required? to Yes, then open Users and groups and assign the administrators (or a group of them).
- In Airgate, under Identity provider, keep Metadata URL selected, paste the URL into App federation metadata URL and select Add provider. The dialog shows the IdP’s Entity ID, Sign-on URL and Signing certificates that Airgate found.
Entra ID sends the email in the standard claims; Airgate looks for NameID,
emailaddress, email and mail.
Microsoft Entra ID with OpenID Connect
Section titled “Microsoft Entra ID with OpenID Connect”- Open Entra ID › App registrations › New registration. Name it
Airgate console, choose Single tenant, under Redirect URI choose Web and paste the Redirect URI (Web) from Airgate. Select Register. - Leave Front-channel logout URL empty and both implicit grant boxes (Access tokens, ID tokens) cleared. Airgate uses the authorization code flow with a client secret.
- Open Certificates & secrets › New client secret and copy the Value.
- Open Token configuration › Add optional claim › ID and add
email. - In Enterprise apps › Airgate console › Properties, set Assignment required? to Yes and assign the administrators under Users and groups.
- In Airgate, enter the Entra ID directory (tenant) ID (it fills in
Issuer URL as
https://login.microsoftonline.com/<tenant id>/v2.0), the Client (application) ID and the Client secret. Select Add provider.
Okta (OpenID Connect)
Section titled “Okta (OpenID Connect)”- In the Okta Admin Console, open Applications › Applications › Create App Integration, choose OIDC - OpenID Connect and Web Application.
- Under Sign-in redirect URIs, paste the Redirect URI (Web) from Airgate. Under Assignments, limit access to the administrators’ group.
- Copy the Client ID and Client secret.
- In Airgate: Issuer URL
https://contoso.okta.com, Client (application) ID, Client secret. Select Add provider.
Okta with SAML: create a SAML 2.0 app, set Single sign-on URL to the
Airgate Reply URL and Audience URI (SP Entity ID) to the Identifier
(Entity ID), set Name ID format to EmailAddress, assign the
administrators, and paste the IdP metadata URL into Airgate.
Google Workspace (SAML)
Section titled “Google Workspace (SAML)”- In the Google Admin console, open Apps › Web and mobile apps › Add
app › Add custom SAML app. Name it
Airgate console. - On Google Identity Provider details, select Download Metadata.
- On Service provider details, enter ACS URL = the Airgate Reply
URL and Entity ID = the Airgate Identifier (Entity ID). Set
Name ID format to
EMAILand Name ID to Basic Information › Primary email. - Finish the wizard, then open the app’s User access and turn it ON only for the organizational unit or group of administrators.
- In Airgate, choose Paste metadata XML and paste the downloaded file into IdP metadata XML. Select Add provider.
Google with OpenID Connect also works: Issuer URL
https://accounts.google.com with an OAuth client of type Web application
from the Google Cloud console.
Other SAML IdPs (ADFS, Ping, Keycloak, OneLogin)
Section titled “Other SAML IdPs (ADFS, Ping, Keycloak, OneLogin)”Register a relying party or client with the Entity ID and the ACS URL (HTTP-POST binding). Send the email as an attribute or as an email-format NameID, and sign the response or the assertion. The IdP’s sign-on endpoint must support the HTTP-Redirect binding. Give Airgate the IdP metadata URL or XML.
If your IdP uses other claim names, set them under Claim names (advanced): Email, Display name, Groups / roles.
Step 3: Test
Section titled “Step 3: Test”- On Settings › Single sign-on, select Test on the provider’s row. Test works before the provider is enabled.
- Sign in at the IdP. You return to a Test sign-in dialog that shows This user can sign in or This user cannot sign in with the reason, the Email, Name, Role, the Groups / roles the IdP sent and every claim. Nobody is signed in and no account changes.
Step 4: Sign in
Section titled “Step 4: Sign in”- Turn on Enabled (shown on the sign-in page) if it is off.
- Sign out, select Sign in with SSO on the sign-in page, enter the Work email and select Continue.
- After the IdP sign-in, the console opens. The new administrator appears under Settings › Administrators with the badge SSO.
Good to know
Section titled “Good to know”- A local administrator with the same email can also sign in through SSO and keeps the role set in the console.
- An email that belongs to an administrator of another tenant is refused.
- Deleting a provider disables the administrators it created; local administrators are not affected.
- Sign-in must start from Airgate (the sign-in page, or an IdP app tile that
opens the console’s
/login). IdP-initiated SAML is not accepted. - The latest error is shown on the provider’s row (Last error) and in the provider dialog.
Troubleshooting
Section titled “Troubleshooting”| Message | Cause | Fix |
|---|---|---|
Single sign-on is not set up for contoso.com. Sign in with your password. |
No enabled provider has that email domain. | Add the domain under Email domains and turn the provider on. |
… is not in this provider's domains (…) |
The IdP sends another email (for example a .onmicrosoft.com UPN). |
Send the primary email, or add that domain. |
the IdP sent no email address (looked for …) |
No email claim. | Add an email claim at the IdP, or set Claim names (advanced) › Email. |
… is an administrator of another tenant and cannot sign in here |
The email is already an administrator elsewhere. | Use another account. |
the console account … is disabled |
The administrator was disabled in Airgate. | Enable it under Settings › Administrators. |
the IdP returned no state; start the sign-in from the Airgate sign-in page (IdP-initiated sign-in is not supported) |
The sign-in started at the IdP. | Start at the Airgate sign-in page. |
this sign-in expired or was already used; start again from the sign-in page |
The browser came back too late or twice. | Sign in again. |
AADSTS50011 (reply URL does not match) |
The Reply URL or redirect URI at Entra ID differs from the one Airgate shows. | Copy it again; check PUBLIC_URL. |
| SAML is rejected after it worked before | The IdP rolled its signing certificate. | Open the provider and select Save: a metadata URL is fetched again at each save. With pasted XML, paste the new metadata. |