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

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,
    "oidc_config": {
      "issuer": "https://your-org.okta.com",
      "client_id": "<oidc-client-id>",
      "client_secret": "<oidc-client-secret>",
      "request_scopes": ["openid", "profile", "email"],
      "root_url": "https://<dashboard-host>:7443",
      "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 API7 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.

❹ oidc_config.issuer is the OIDC issuer URL used for discovery, and oidc_config.root_url is the Dashboard's own public base URL, from which the callback URL is derived. Both are required.

❺ oidc_config.client_id and oidc_config.client_secret are the OAuth client credentials issued by your identity provider.

❻ oidc_config.attributes maps identity provider claims to developer fields such as username, email, and name.

SAML

read -rp "Developer Portal URL: " API7_PORTAL_URL && export API7_PORTAL_URL
read -rp "IdP metadata URL: " IDP_METADATA_URL && export IDP_METADATA_URL
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,
    "saml_config": {
      "sp_root_url": "'"${API7_PORTAL_URL}"'",
      "idp_metadata_url": "'"${IDP_METADATA_URL}"'",
      "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.

❹ saml_config.sp_root_url is the portal's own public base URL, which API7 uses to derive the Service Provider entity ID and the assertion-consumer URL. It is required.

❺ saml_config.idp_metadata_url points to the IdP metadata document that API7 uses to configure the SAML integration.

❻ saml_config.attributes maps SAML attributes to developer fields.

LDAP

read -rp "LDAP host: " LDAP_HOST && export LDAP_HOST
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,
    "ldap_config": {
      "host": "'"${LDAP_HOST}"'",
      "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.

❹ ldap_config.host, ldap_config.port, ldap_config.base_dn, ldap_config.bind_dn, and ldap_config.bind_password define how API7 connects to and searches your LDAP directory.

❺ ldap_config.identifier selects the LDAP attribute used as the login identifier, such as uid or sAMAccountName.

❻ ldap_config.attributes maps LDAP attributes to developer fields.

CAS

read -rp "CAS server URL: " CAS_URL && export CAS_URL
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,
    "cas_config": {
      "url": "'"${CAS_URL}"'/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.

❹ cas_config.url is the base URL of your CAS server.

❺ cas_config.send_service controls whether API7 includes the service parameter in CAS requests.

❻ cas_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}"

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.

Additional Resources

• Developers
• Register and Log In
• SSO for the Dashboard