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.
Prerequisites
Create a token by following Obtain a Token from the Dashboard and export it:
export API_KEY="a7ee-xxxxxxxxxxxxx"
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 -k "https://localhost:7443/api/login_options" \
-H "X-API-KEY: ${API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"name": "Okta SSO",
"provider_type": "oidc",
"disable": false,
"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"
}
}
}'
If you are not running locally, replace localhost with your Dashboard host. The -k flag is required if the Dashboard uses a self-signed TLS certificate.
❶ name is the display name shown to developers on the sign-in page.
❷ provider_type selects the SSO protocol. Use oidc for OpenID Connect providers such as Okta, Auth0, or Keycloak.
❸ disable: false enables the login option immediately after creation.
❹ config.issuer is the OIDC issuer URL used for discovery.
❺ config.client_id and config.client_secret are the OAuth client credentials issued by your identity provider.
❻ config.attributes maps identity provider claims to developer fields such as username, email, and name.
SAML
curl -k "https://localhost:7443/api/login_options" \
-H "X-API-KEY: ${API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"name": "Corporate SAML",
"provider_type": "saml",
"disable": false,
"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"
}
}
}'
❶ name is the display name shown to developers on the sign-in page.
❷ provider_type: "saml" selects SAML 2.0 as the authentication protocol.
❸ disable: false enables the login option immediately after creation.
❹ config.entity_id is the Service Provider entity ID used by the portal.
❺ config.idp_metadata_url points to the IdP metadata document that API7 uses to configure the SAML integration.
❻ config.attributes maps SAML attributes to developer fields.
LDAP
curl -k "https://localhost:7443/api/login_options" \
-H "X-API-KEY: ${API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"name": "Active Directory",
"provider_type": "ldap",
"disable": false,
"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"
}
}
}'
❶ name is the display name shown to developers on the sign-in page.
❷ provider_type: "ldap" selects LDAP authentication.
❸ disable: false enables the login option immediately after creation.
❹ config.host, config.port, config.base_dn, config.bind_dn, and config.bind_password define how API7 connects to and searches your LDAP directory.
❺ config.identifier selects the LDAP attribute used as the login identifier, such as uid or sAMAccountName.
❻ config.attributes maps LDAP attributes to developer fields.
CAS
curl -k "https://localhost:7443/api/login_options" \
-H "X-API-KEY: ${API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"name": "CAS Server",
"provider_type": "cas",
"disable": false,
"config": {
"url": "https://cas.example.com/cas",
"send_service": true,
"ssl_verify": true,
"attributes": {
"username": "uid",
"email": "mail",
"name": "cn"
}
}
}'
❶ name is the display name shown to developers on the sign-in page.
❷ provider_type: "cas" selects CAS as the authentication protocol.
❸ disable: false enables the login option immediately after creation.
❹ config.url is the base URL of your CAS server.
❺ config.send_service controls whether API7 includes the service parameter in CAS requests.
❻ config.attributes maps CAS attributes to developer fields.
Managing Login Options
Enable/Disable
Toggle a login option without deleting its configuration:
curl -k -X PATCH "https://localhost:7443/api/login_options/{login_option_id}" \
-H "X-API-KEY: ${API_KEY}" \
-H "Content-Type: application/json" \
-d '[
{
"op": "replace",
"path": "/disable",
"value": true
}
]'
Delete
curl -k -X DELETE "https://localhost:7443/api/login_options/{login_option_id}" \
-H "X-API-KEY: ${API_KEY}"
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.