External Identity Provider Management

Overview

The External Identity Provider Management API provides endpoints for configuring and managing external identity providers for social login and enterprise SSO.

Endpoint List

Method	Endpoint	Description
GET	`/api/admin/external-providers`	List providers
GET	`/api/admin/external-providers/:id`	Get provider details
POST	`/api/admin/external-providers`	Create provider
PUT	`/api/admin/external-providers/:id`	Update provider
DELETE	`/api/admin/external-providers/:id`	Delete provider
POST	`/api/admin/external-providers/:id/test`	Test connection
POST	`/api/admin/external-providers/:id/enable`	Enable provider
POST	`/api/admin/external-providers/:id/disable`	Disable provider

List Providers

Retrieve a list of configured external identity providers.

Endpoint

GET /api/admin/external-providers

Query Parameters

Parameter	Type	Required	Description
`limit`	integer	-	Number of items (default: 20)
`cursor`	string	-	Pagination cursor
`type`	string	-	Filter by provider type
`status`	string	-	Filter by status

Request Example

curl -X GET "https://{tenant-domain}/api/admin/external-providers" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "items": [
    {
      "id": "provider_google",
      "name": "google",
      "display_name": "Google",
      "type": "oauth2",
      "status": "active",
      "login_count": 1250,
      "created_at": 1705881600,
      "updated_at": 1705968000
    },
    {
      "id": "provider_okta",
      "name": "okta-enterprise",
      "display_name": "Okta SSO",
      "type": "oidc",
      "status": "active",
      "login_count": 500,
      "created_at": 1705968000,
      "updated_at": 1706054400
    }
  ],
  "total": 3
}

Get Provider Details

Retrieve detailed information for a specified provider.

Endpoint

GET /api/admin/external-providers/:id

Path Parameters

Parameter	Type	Required	Description
`id`	string	✓	Provider ID

Request Example

curl -X GET "https://{tenant-domain}/api/admin/external-providers/provider_google" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "id": "provider_google",
  "name": "google",
  "display_name": "Google",
  "type": "oauth2",
  "status": "active",
  "config": {
    "client_id": "123456789.apps.googleusercontent.com",
    "authorization_endpoint": "https://accounts.google.com/o/oauth2/v2/auth",
    "token_endpoint": "https://oauth2.googleapis.com/token",
    "userinfo_endpoint": "https://openidconnect.googleapis.com/v1/userinfo",
    "scopes": ["openid", "profile", "email"],
    "response_type": "code",
    "grant_type": "authorization_code"
  },
  "attribute_mapping": {
    "email": "email",
    "name": "name",
    "picture": "picture",
    "email_verified": "email_verified"
  },
  "options": {
    "allow_signup": true,
    "sync_user_profile": true,
    "link_existing_accounts": true
  },
  "login_count": 1250,
  "last_login_at": 1706140800,
  "created_at": 1705881600,
  "updated_at": 1705968000
}

Create Provider

Configure a new external identity provider.

Endpoint

POST /api/admin/external-providers

Request Body

Field	Type	Required	Description
`name`	string	✓	Provider name (alphanumeric, hyphens)
`display_name`	string	✓	Display name
`type`	string	✓	Provider type (`oauth2`, `oidc`, `saml`)
`config`	object	✓	Provider configuration
`attribute_mapping`	object	-	Attribute mapping
`options`	object	-	Option settings

Preset Providers

Common providers can be easily configured using presets:

curl -X POST "https://{tenant-domain}/api/admin/external-providers" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "github",
    "display_name": "GitHub",
    "type": "oauth2",
    "preset": "github",
    "config": {
      "client_id": "your_github_client_id",
      "client_secret": "your_github_client_secret"
    }
  }'

Custom OIDC Provider

curl -X POST "https://{tenant-domain}/api/admin/external-providers" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "corporate-idp",
    "display_name": "Corporate Auth",
    "type": "oidc",
    "config": {
      "client_id": "authrim-client",
      "client_secret": "secret",
      "issuer": "https://idp.example.com",
      "discovery_url": "https://idp.example.com/.well-known/openid-configuration",
      "scopes": ["openid", "profile", "email", "groups"]
    },
    "attribute_mapping": {
      "email": "email",
      "name": "name",
      "groups": "groups"
    },
    "options": {
      "allow_signup": true,
      "sync_user_profile": true,
      "link_existing_accounts": true,
      "required_groups": ["authrim-users"]
    }
  }'

Response Example

{
  "id": "provider_corporate_idp",
  "name": "corporate-idp",
  "display_name": "Corporate Auth",
  "type": "oidc",
  "status": "inactive",
  "created_at": 1706140800
}

Update Provider

Update existing provider settings.

Endpoint

PUT /api/admin/external-providers/:id

Request Example

curl -X PUT "https://{tenant-domain}/api/admin/external-providers/provider_google" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Google Account",
    "options": {
      "allow_signup": false
    }
  }'

Delete Provider

Delete a provider.

Endpoint

DELETE /api/admin/external-providers/:id

Request Example

curl -X DELETE "https://{tenant-domain}/api/admin/external-providers/provider_old" \
  -H "Authorization: Bearer {token}"

Test Connection

Test that the provider configuration is working correctly.

Endpoint

POST /api/admin/external-providers/:id/test

Request Example

curl -X POST "https://{tenant-domain}/api/admin/external-providers/provider_corporate_idp/test" \
  -H "Authorization: Bearer {token}"

Response Example (Success)

{
  "success": true,
  "checks": [
    {
      "name": "discovery_endpoint",
      "status": "passed",
      "message": "OIDC discovery endpoint is reachable"
    },
    {
      "name": "jwks_endpoint",
      "status": "passed",
      "message": "Retrieved public keys from JWKS endpoint"
    },
    {
      "name": "authorization_endpoint",
      "status": "passed",
      "message": "Authorization endpoint is valid"
    }
  ]
}

Response Example (Error)

{
  "success": false,
  "checks": [
    {
      "name": "discovery_endpoint",
      "status": "failed",
      "message": "Cannot reach OIDC discovery endpoint",
      "error": "Connection timeout"
    }
  ]
}

Enable Provider

Enable a provider for use in login.

Endpoint

POST /api/admin/external-providers/:id/enable

Request Example

curl -X POST "https://{tenant-domain}/api/admin/external-providers/provider_corporate_idp/enable" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "id": "provider_corporate_idp",
  "status": "active",
  "enabled_at": 1706227200
}

Disable Provider

Disable a provider.

Endpoint

POST /api/admin/external-providers/:id/disable

Request Example

curl -X POST "https://{tenant-domain}/api/admin/external-providers/provider_corporate_idp/disable" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "id": "provider_corporate_idp",
  "status": "inactive",
  "disabled_at": 1706313600
}

Supported Presets

Preset	Type	Description
`google`	oauth2	Google
`github`	oauth2	GitHub
`microsoft`	oidc	Microsoft / Azure AD
`apple`	oidc	Apple
`facebook`	oauth2	Facebook
`twitter`	oauth2	Twitter / X
`linkedin`	oauth2	LinkedIn
`slack`	oidc	Slack
`okta`	oidc	Okta
`auth0`	oidc	Auth0

Attribute Mapping

Map attributes retrieved from the provider to Authrim user attributes.

{
  "attribute_mapping": {
    "email": "email",
    "name": "displayName",
    "given_name": "firstName",
    "family_name": "lastName",
    "picture": "avatar",
    "groups": "memberOf"
  }
}

The left side is the Authrim attribute name, the right side is the attribute name returned from the provider.