Configure SSO for the Developer Portal
The Developer Portal supports Single Sign-On (SSO) through external identity providers, allowing developers to authenticate using their existing organizational credentials. SSO is configured as login options in the Provider Portal, separate from the Dashboard SSO configuration.
Supported Protocols
| Protocol | Description |
|---|---|
| OIDC | OpenID Connect. Integrates with providers such as Keycloak, Okta, Auth0, and Azure AD. |
| SAML | Security Assertion Markup Language 2.0. Integrates with enterprise identity providers. |
| LDAP | Lightweight Directory Access Protocol. Integrates with directory services such as Active Directory. |
| CAS | Central Authentication Service. Integrates with CAS servers. |
Create a Login Option
OIDC
curl "https://{ADMIN_API_URL}/api/portals/{portal_id}/login_options" \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Okta SSO",
"provider_type": "oidc",
"enabled": true,
"config": {
"issuer": "https://your-org.okta.com",
"client_id": "<oidc-client-id>",
"client_secret": "<oidc-client-secret>",
"request_scopes": ["openid", "profile", "email"],
"ssl_verify": true,
"attributes": {
"username": "preferred_username",
"email": "email",
"name": "name"
}
}
}'
OIDC configuration fields:
| Field | Required | Description |
|---|---|---|
issuer | Yes | The OIDC issuer URL. |
client_id | Yes | The OAuth 2.0 client ID. |
client_secret | Yes | The OAuth 2.0 client secret. |
request_scopes | No | Scopes to request during authentication. |
root_url | No | Override the root URL for callback generation. |
ssl_verify | No | Whether to verify TLS certificates (default: true). |
callback_url | Read-only | Auto-generated callback URL. Configure this in your identity provider. |
logout_url | No | URL to redirect to after logout. |
attributes | No | Mapping from identity provider claims to developer fields (username, email, name). |
SAML
curl "https://{ADMIN_API_URL}/api/portals/{portal_id}/login_options" \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Corporate SAML",
"provider_type": "saml",
"enabled": true,
"config": {
"entity_id": "https://portal.example.com",
"idp_metadata_url": "https://idp.example.com/metadata",
"sign_request": true,
"attributes": {
"username": "urn:oid:0.9.2342.19200300.100.1.1",
"email": "urn:oid:0.9.2342.19200300.100.1.3",
"name": "urn:oid:2.5.4.3"
}
}
}'
SAML configuration fields:
| Field | Required | Description |
|---|---|---|
entity_id | Yes | The Service Provider entity ID. |
idp_metadata_url | Yes | URL to the Identity Provider's SAML metadata. |
sp_root_url | No | Override the Service Provider root URL. |
sign_request | No | Whether to sign SAML requests (default: false). |
certificate | No | X.509 certificate for request signing. Auto-generated if signing is enabled and no certificate is provided. |
private_key | No | Private key for request signing. |
attributes | No | Mapping from SAML attributes to developer fields. |
logout_idp_session | No | Whether to perform single logout with the IdP. |
LDAP
curl "https://{ADMIN_API_URL}/api/portals/{portal_id}/login_options" \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Active Directory",
"provider_type": "ldap",
"enabled": true,
"config": {
"host": "ldap.example.com",
"port": 636,
"base_dn": "dc=example,dc=com",
"bind_dn": "cn=admin,dc=example,dc=com",
"bind_password": "<ldap-password>",
"identifier": "uid",
"use_ssl": true,
"ssl_verify": true,
"attributes": {
"username": "uid",
"email": "mail",
"name": "cn"
}
}
}'
LDAP configuration fields:
| Field | Required | Description |
|---|---|---|
host | Yes | LDAP server hostname. |
port | Yes | LDAP server port (389 for LDAP, 636 for LDAPS). |
base_dn | Yes | Base distinguished name for user searches. |
bind_dn | Yes | DN used to bind to the LDAP server. |
bind_password | Yes | Password for the bind DN. |
identifier | Yes | LDAP attribute used as the login identifier (for example, uid or sAMAccountName). |
use_ssl | No | Whether to use LDAPS (default: false). |
ssl_verify | No | Whether to verify TLS certificates (default: true). |
root_ca_cert | No | Custom CA certificate for TLS verification. |
client_cert | No | Client certificate for mTLS. |
client_key | No | Client private key for mTLS. |
timeout | No | Connection timeout in seconds. |
attributes | No | Mapping from LDAP attributes to developer fields. |
CAS
curl "https://{ADMIN_API_URL}/api/portals/{portal_id}/login_options" \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "CAS Server",
"provider_type": "cas",
"enabled": true,
"config": {
"url": "https://cas.example.com/cas",
"send_service": true,
"ssl_verify": true,
"attributes": {
"username": "uid",
"email": "mail",
"name": "cn"
}
}
}'
CAS configuration fields:
| Field | Required | Description |
|---|---|---|
url | Yes | CAS server URL. |
send_service | No | Whether to send the service parameter in CAS requests. |
ssl_verify | No | Whether to verify TLS certificates (default: true). |
attributes | No | Mapping from CAS attributes to developer fields. |
Managing Login Options
Enable/Disable
Toggle a login option without deleting its configuration:
curl -X PUT "https://{ADMIN_API_URL}/api/portals/{portal_id}/login_options/{login_option_id}" \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"enabled": false
}'
Delete
curl -X DELETE "https://{ADMIN_API_URL}/api/portals/{portal_id}/login_options/{login_option_id}" \
-H "Authorization: Bearer $API_TOKEN"
caution
At least one login option must remain enabled at all times. The built-in login option can be disabled but not deleted.
Sensitive Field Handling
Sensitive fields (client_secret, private_key, bind_password, client_key) are masked in API responses after creation. To update a sensitive field, include the new value in the update request. Fields that support the $env://VAR_NAME syntax can reference environment variables instead of containing the secret directly.
Developers Authenticated via SSO
Developers who authenticate through an SSO login option have their provider field set to sso. Their accounts are created automatically on first login, with profile information populated from the identity provider attributes.