Sign in
Admin

Create Oauth Provider

Changed on

Create a new OAuth or SAML provider (admin only).

Audit-log payload includes the full created snapshot with non-secret fields verbatim and <redacted> markers for secrets that were submitted in the request body.

post/settings/oauth-providers/

Request

  • The document declares no server URL.
  • Auth: one of:
    • OAuth 2 (password, token URL /api/auth/login)
    • API key in header X-Api-Key
    • API key in query parameter api_key

Request body

slugstring required

URL-safe identifier used in callback URLs (e.g. 'google', 'azure-ad'). Lowercase, digits, and hyphens only.

display_namestring required

Human-readable label shown on the login page button.

provider_type'google' | 'microsoft' | 'oidc' | 'saml' | 'github' required

OAuth or SAML provider type. 'google' and 'microsoft' auto-populate the discovery URL; 'oidc' is generic OAuth/OIDC; 'github' uses GitHub's fixed OAuth2 endpoints (no discovery URL); 'saml' is available only on SAML-enabled deployments.

client_idstring nullable

OAuth client ID issued by the IdP. Required for OAuth/OIDC providers; omit for SAML.

client_secretstring nullable

OAuth client secret issued by the IdP. Stored encrypted; never returned in responses. Required for OAuth/OIDC providers; omit for SAML.

discovery_urlstring nullable

OIDC discovery URL ending in .well-known/openid-configuration. Auto-populated for Google and Microsoft.

authorize_urlstring nullable

Authorization endpoint. Only needed when discovery_url is not set.

token_urlstring nullable

Token endpoint. Only needed when discovery_url is not set.

userinfo_urlstring nullable

Userinfo endpoint. Only needed when discovery_url is not set.

idp_entity_idstring nullable

SAML IdP entityID. Required for SAML providers.

idp_sso_urlstring nullable

SAML IdP SSO URL (HTTP-Redirect or HTTP-POST binding). Required for SAML providers.

idp_certificatestring nullable

SAML IdP signing certificate (PEM). Required for SAML providers. Stored Fernet-encrypted at rest; never returned in responses.

sp_entity_idstring nullable

SP entityID for this provider. Required for SAML providers. Default suggestion: {public_api_url}/auth/saml/{slug}.

scopesstring

Space-separated OAuth scopes.

default_rolestring

Role assigned to new users created via this provider: 'viewer', 'editor', or 'admin'.

group_claimstring nullable

Name of the JWT/userinfo claim (or SAML attribute) that contains group memberships. Set to enable group-based role mapping.

group_role_mappingobject nullable

JSON object mapping IdP group names to GeoLens roles ('viewer', 'editor' or 'admin'). A user in several mapped groups gets the most privileged of their roles; a user in none gets default_role.

enabledboolean

Whether the provider button appears on the login page.

Response

Successful Response

idstring uuid required

Unique provider identifier.

slugstring required

URL-safe identifier used in the callback URL.

display_namestring required

Label shown on the login page button.

provider_typestring required

Provider type: 'google', 'microsoft', 'oidc', or 'saml'.

client_idstring nullable

OAuth client ID. Visible to admins; never exposes client_secret. Null for SAML providers.

discovery_urlstring nullable

OIDC discovery URL.

authorize_urlstring nullable

Authorization endpoint.

token_urlstring nullable

Token endpoint.

userinfo_urlstring nullable

Userinfo endpoint.

idp_entity_idstring nullable

SAML IdP entityID (SAML providers only).

idp_sso_urlstring nullable

SAML IdP SSO URL (SAML providers only).

sp_entity_idstring nullable

SP entityID for this SAML provider (SAML providers only).

scopesstring required

Space-separated OAuth scopes.

default_rolestring required

Default role assigned to new users.

group_claimstring nullable

Claim name used for group-based role mapping.

group_role_mappingobject nullable

Group-to-role mapping rules.

enabledboolean required

Whether the provider button appears on the login page.

created_atstring date-time required

Timestamp the provider was created.

updated_atstring date-time required

Timestamp the provider was last updated.

Changes