Console single sign-on API
The console single sign-on API lets administrators of a tenant sign in to the Airgate console through their own identity provider (IdP): Microsoft Entra ID, Okta, Google, AD FS, Ping, Keycloak, or any SAML 2.0 or OpenID Connect provider. It backs Settings › Single sign-on. Password sign-in keeps working next to it.
Base path and permissions
Section titled “Base path and permissions”Provider management routes are relative to /api/v1/t/{tenant}, where {tenant} is the tenant slug or ID. The sign-in routes are public and live under /api/v1/auth/sso/. See API overview for authentication.
| Method | Path | Permission | Purpose |
|---|---|---|---|
GET |
/sso-providers |
admin:read |
List providers |
GET |
/sso-providers/draft |
admin:write |
Reserve a provider ID and get the addresses to register at the IdP |
POST |
/sso-providers |
admin:write |
Create a provider |
POST |
/sso-providers/idp-metadata |
admin:write |
Preview parsed SAML IdP metadata |
GET |
/sso-providers/test-results/{code} |
admin:read |
Result of a test sign-in |
GET |
/sso-providers/{id} |
admin:read |
Read a provider |
PUT |
/sso-providers/{id} |
admin:write |
Update a provider |
DELETE |
/sso-providers/{id} |
admin:write |
Delete a provider |
POST |
/api/v1/auth/sso/discover |
Public | Find the provider for an email address |
GET |
/api/v1/auth/sso/{id}/start |
Public | Start a sign-in (redirect to the IdP) |
GET |
/api/v1/auth/sso/{id}/metadata |
Public | SAML service-provider metadata |
POST |
/api/v1/auth/sso/{id}/acs |
Public | SAML Assertion Consumer Service |
GET |
/api/v1/auth/sso/{id}/callback |
Public | OpenID Connect redirect URI |
POST |
/api/v1/auth/sso/exchange |
Public | Swap a one-time sign-in code for a console token |
Every provider change is audited (object type sso_provider).
How a sign-in works
Section titled “How a sign-in works”- The sign-in page posts the work email to
POST /api/v1/auth/sso/discover. The email domain selects the provider; a domain belongs to one provider across the whole platform. - The browser goes to
GET /api/v1/auth/sso/{id}/start, which records the sign-in and redirects to the IdP. - The IdP returns to the ACS URL (SAML, HTTP-POST binding) or the redirect URI (OpenID Connect, authorization code with PKCE). Airgate validates the signature, audience, issuer, time window and request ID or nonce, and accepts each response once. IdP-initiated SAML sign-in is not supported.
- Airgate checks the identity and finds or creates the administrator account. The browser lands on
/login?sso_code=..., and the page swaps the code for a console token withPOST /api/v1/auth/sso/exchange. A failure lands on/login?sso_error=...and is stored on the provider aslast_error.
Identity checks and accounts
Section titled “Identity checks and accounts”- The asserted email must belong to one of the provider’s domains.
- The role comes from
role_mappings(IdPgroupto Airgaterole), compared case-insensitively against the groups claim. When several mappings match, the strongest role wins:tenant_admin>network_admin>helpdesk>read_only>guest_operator. With no match,default_roleapplies; an empty default role means no access. - The first sign-in creates an administrator with no password. Later sign-ins update the name and role from the IdP. A user who lost every mapped group is refused.
- An existing local administrator with the same email in the same tenant may sign in through SSO and keeps the role set in the console.
- An email that belongs to an administrator of another tenant, or to a platform administrator, is refused.
- Deleting a provider disables the administrators it created.
Default claim names
Section titled “Default claim names”| SAML attribute | OpenID Connect claim | |
|---|---|---|
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress, email, mail, emailAddress, urn:oid:0.9.2342.19200300.100.1.3, .../claims/name, .../claims/upn, then a NameID that is an email |
email, preferred_username, upn |
|
| Name | http://schemas.microsoft.com/identity/claims/displayname, displayName, name, cn, then given name and surname |
name |
| Groups | http://schemas.microsoft.com/ws/2008/06/identity/claims/groups, .../claims/role, groups, memberOf, role, roles, urn:oid:1.3.6.1.4.1.5923.1.5.1.1 |
groups, roles |
Override them with config.email_claim, config.name_claim and config.groups_claim.
Providers
Section titled “Providers”Provider object
Section titled “Provider object”{ "id": "4b1f...", "tenant_id": "dc40...", "name": "Entra ID", "protocol": "saml", "enabled": true, "domains": ["contoso.com"], "config": { "idp_metadata_url": "https://login.microsoftonline.com/<tenant>/federationmetadata/2007-06/federationmetadata.xml?appid=<app>", "email_claim": "", "name_claim": "", "groups_claim": "" }, "client_secret": "", "role_mappings": [{"group": "Airgate-Admins", "role": "tenant_admin"}], "default_role": "", "users": 3, "last_login_at": "...", "last_error": "", "last_error_at": null, "created_at": "...", "updated_at": "...", "sp": { "entity_id": "https://airgate.contoso.com/api/v1/auth/sso/4b1f.../metadata", "acs_url": "https://airgate.contoso.com/api/v1/auth/sso/4b1f.../acs", "metadata_url": "https://airgate.contoso.com/api/v1/auth/sso/4b1f.../metadata", "sign_on_url": "https://airgate.contoso.com/login" }, "idp": {"entity_id": "...", "sso_url": "...", "certificates": [{"subject": "...", "not_after": "...", "sha256": "..."}]}}| Field | Type | Meaning |
|---|---|---|
id |
UUID | Create only: the ID returned by GET /sso-providers/draft, so the addresses you already registered at the IdP stay valid |
name |
string | Required, at most 100 characters |
protocol |
string | saml or oidc. Cannot change after creation. |
enabled |
boolean | |
domains |
array of string | At least one email domain. It routes sign-ins to this provider and limits who it can sign in. A domain used by another provider returns 409. |
config.idp_metadata_url / config.idp_metadata_xml |
string | SAML: the IdP metadata URL (https) or the pasted metadata XML. The metadata must have an HTTP-Redirect sign-on URL and a signing certificate. |
config.issuer |
string | OpenID Connect: the issuer URL (https), for example https://login.microsoftonline.com/<tenant id>/v2.0 |
config.client_id |
string | OpenID Connect: required |
config.scopes |
string | OpenID Connect: extra scopes, space separated |
config.email_claim, config.name_claim, config.groups_claim |
string | Override the default claim names |
client_secret |
string | OpenID Connect client secret. Encrypted at rest and never returned. On update, omit it or send null to keep the stored value. |
role_mappings |
array | {"group": "<IdP group or role>", "role": "<Airgate role>"}. Every mapping needs a group. |
default_role |
string | Role when no mapping matches; empty means no access. Either a mapping or a default role is required. |
Roles are tenant_admin, network_admin, helpdesk, read_only and guest_operator. You can only map roles whose permissions you hold yourself.
sp lists what to register at the IdP: for SAML the Identifier (Entity ID), Reply URL (ACS URL) and metadata URL; for OpenID Connect the redirect_uri (.../auth/sso/{id}/callback). idp summarises the parsed SAML metadata. users counts the administrators the provider signed in.
A SAML metadata URL is fetched again at every save, so saving picks up a rolled signing certificate; if the IdP is unreachable, the stored copy is kept. Metadata URLs and OpenID Connect issuers must use https and may not point to private addresses.
GET /sso-providers/draft
Section titled “GET /sso-providers/draft”Permission: admin:write
Query protocol=saml or protocol=oidc. Returns {"id": "...", "sp": {...}}: a new provider ID and the addresses to register at the IdP before you create the provider. Nothing is stored.
POST /sso-providers
Section titled “POST /sso-providers”Permission: admin:write
curl -s -X POST "$AIRGATE/api/v1/t/$TENANT/sso-providers" \ -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \ -d '{"name": "Entra ID", "protocol": "oidc", "enabled": true, "domains": ["contoso.com"], "config": {"issuer": "https://login.microsoftonline.com/<tenant id>/v2.0", "client_id": "<application id>"}, "client_secret": "<client secret>", "role_mappings": [{"group": "<group object id>", "role": "tenant_admin"}]}'Returns 201 with the provider. 400 for a validation error (the message says what is missing), 409 when a domain belongs to another provider or the ID is taken.
PUT /sso-providers/{id}
Section titled “PUT /sso-providers/{id}”Permission: admin:write
Same body as create. Returns 200 with the provider.
DELETE /sso-providers/{id}
Section titled “DELETE /sso-providers/{id}”Permission: admin:write
Returns 204. The administrators the provider created are disabled.
POST /sso-providers/idp-metadata
Section titled “POST /sso-providers/idp-metadata”Permission: admin:write
Body {"url": "https://..."} or {"xml": "<EntityDescriptor ...>"}. Returns the parsed IdP summary (entity_id, sso_url, certificates) so you can check it before saving.
Test sign-in
Section titled “Test sign-in”The console opens /api/v1/auth/sso/{id}/start?test=1 (this works for a disabled provider too). After the IdP, the browser returns to Settings › Single sign-on with a test code, and the page reads the result.
GET /sso-providers/test-results/{code}
Section titled “GET /sso-providers/test-results/{code}”Permission: admin:read
{"ok": true, "identity": {"subject": "...", "email": "alice@contoso.com", "name": "Alice", "groups": ["Airgate-Admins"], "claims": {"...": ["..."]}}, "role": "tenant_admin", "matched_groups": ["Airgate-Admins"], "account": "...what a real sign-in would do...", "at": "..."}Nobody is signed in and no account changes during a test.
Public sign-in routes
Section titled “Public sign-in routes”These routes need no token. Browsers call them during sign-in; you rarely call them yourself.
POST /api/v1/auth/sso/discover
Section titled “POST /api/v1/auth/sso/discover”Body {"email": "alice@contoso.com"}. Returns {"provider_id", "name", "protocol", "start_url"}. Returns 404 when the domain has no enabled provider (Single sign-on is not set up for contoso.com. Sign in with your password.).
GET /api/v1/auth/sso/{id}/start
Section titled “GET /api/v1/auth/sso/{id}/start”Query login_hint (the email, passed to the IdP) and test=1 for a test sign-in. Responds 302 to the IdP.
GET /api/v1/auth/sso/{id}/metadata
Section titled “GET /api/v1/auth/sso/{id}/metadata”The SAML service-provider metadata (XML) to import at the IdP.
POST /api/v1/auth/sso/{id}/acs
Section titled “POST /api/v1/auth/sso/{id}/acs”The SAML Assertion Consumer Service. The IdP posts the SAML response here.
GET /api/v1/auth/sso/{id}/callback
Section titled “GET /api/v1/auth/sso/{id}/callback”The OpenID Connect redirect URI. The IdP returns the authorization code here.
POST /api/v1/auth/sso/exchange
Section titled “POST /api/v1/auth/sso/exchange”Body {"code": "..."}. Returns {"token", "expires_at", "principal"}, the same as POST /api/v1/auth/login. Codes are single-use and expire after 2 minutes (401: this sign-in link expired; sign in again).