#OIDC Management

ACP can redirect users to a standards-based OIDC identity provider and create or update their platform identity after successful login.

Use the Form tab for the shortest initial integration. Use the YAML tab when the returned username Claim must be selected explicitly, Claims must be remapped, UserInfo must be queried, or OIDC groups and extra fields are required. See Add OIDC Using YAML.

#Before You Begin

Prepare these values:

• Issuer URL, labeled in ACP as Server Provider URL.
• Client ID.
• Client Secret, labeled in ACP as Client Key.
• One representative test account with an email address that is not already used by an ACP local user or another IDP.
• A stable username Claim returned for that test account. The tested YAML fallback uses preferred_username.

Register this exact callback with the upstream identity provider:

https://<ACP_ADDRESS>/dex/callback

ACP derives the callback from the platform address. The form does not contain a Redirect URI field.

Server Provider URL must be the Issuer root, not an authorization endpoint, token endpoint, or login page. Its discovery document is normally available at this path:

<ISSUER_URL>/.well-known/openid-configuration

You can inspect discovery from a diagnostic host with ACP-equivalent reachability:

curl -fsS 'https://idp.example.com/.well-known/openid-configuration'

For an upstream service that uses a private CA, independently verify the certificate chain with that CA:

curl -fsS --cacert /path/to/oidc-ca.pem \
  'https://idp.example.com/.well-known/openid-configuration'

This external query is preliminary evidence. ACP Connector creation is the cluster-side discovery and reachability check.

#Confirm the Returned Claims

Ask the upstream identity administrator to provide the ID token or UserInfo Claim names for one representative account. Claim names are case-sensitive. ACP Connector creation validates discovery and client reachability, but it does not prove that a real user's token contains the required Claims.

Complete one real browser login before rollout and inspect the generated ACP user. That login is the authoritative check for Claim availability, mapping, collision behavior, and group restrictions.

#Add OIDC Using the Form

1. Go to Users > IDP.
2. Click Add OIDC.
3. Complete Basic Info: Name, Display Name, and optional Description.
4. Complete Server Setting: Server Provider URL, Client ID, and Client Key.
5. Leave Logout URL empty for this validated integration workflow.
6. Click Add.

During creation, ACP reads OIDC discovery from the Issuer URL. An invalid or unreachable Issuer is rejected at this stage. The current creation check does not prove that Client Key is correct or that the upstream TLS certificate is trusted: a Connector with an incorrect key can still be created and then fail during the browser callback, while an untrusted self-signed certificate can be accepted. A real login is therefore required for authentication, and certificate compliance must be assessed separately as described above.

After creation, ACP moves the submitted Client Key to a managed Secret. The stored Connector references that Secret instead of retaining clientSecret in its configuration.

#Console Field Reference

The form does not expose redirectURI, scopes, UserInfo, Claim mappings, group processing, or extra Claims. Configure those fields through YAML only after confirming the upstream response.

#Verify the Integration

1. Start a separate browser session without an ACP login state.
2. Open ACP and select the configured OIDC Display Name.
3. Complete authentication at the upstream identity provider.
4. Confirm that the browser returns to ACP instead of an HTTP 500 error.
5. In Users, find the generated user and verify its IDP source, email, username, and active state.
6. If the username is empty because the upstream response does not contain the default name Claim, recreate or update the Connector with the YAML example below and repeat the login.
7. Assign a minimal role with Manage User Roles.
8. Log in again and confirm that the assigned ACP permission is available.

Connector creation, upstream authentication, ACP user creation, and ACP authorization are separate checkpoints. Verify each checkpoint independently.

#Add OIDC Using YAML

Use Users > IDP > Add OIDC > YAML when the upstream response requires explicit Claim selection or advanced mapping. The complete example below assumes that the upstream response contains sub, preferred_username, email, email_verified, groups, and phone_number, and that the test user belongs to acp-users. Remove optional mappings and group restrictions that the real upstream response does not satisfy.

apiVersion: dex.coreos.com/v1
kind: Connector
id: corporate-oidc
name: Corporate OIDC
type: oidc
metadata:
  name: corporate-oidc
  namespace: cpaas-system
  annotations:
    cpaas.io/description: Corporate OIDC
    # cpaas.io/idp.validation: "false"
  labels:
    cpaas.io/idp.version: v2
spec:
  config:
    issuer: https://idp.example.com
    clientID: <CLIENT_ID>
    clientSecret: <CLIENT_SECRET>
    redirectURI: https://acp.example.com/dex/callback
    scopes:
      - profile
      - email
    getUserInfo: true
    userNameKey: preferred_username
    overrideClaimMapping: true
    claimMapping:
      preferred_username: preferred_username
      email: email
      groups: groups
      phone: phone_number
      mail: email
    claimExtra:
      - field: preferred_username
        type: string
    insecureEnableGroups: true
    allowedGroups:
      - acp-users

Replace the Issuer, credentials, ACP address, Claim names, and allowed group before submission. If the provider does not expose a UserInfo endpoint or all required Claims are already in the ID token, set getUserInfo: false. If group processing is not required, remove insecureEnableGroups, allowedGroups, and claimMapping.groups.

Do not add openid to scopes; the Connector adds it to the authorization request. If the upstream provider requires a provider-specific scope for group Claims, add that scope only after confirming it in the discovery and provider configuration.

Submit this initial configuration through the ACP console YAML tab. ACP moves clientSecret to a managed Secret, and the stored Connector contains clientSecretRef instead. Do not use kubectl apply with an inline clientSecret: the Kubernetes last-applied annotation can retain the submitted secret in the Connector metadata.

#Complete OIDC Field Reference

Top-level and metadata fields:

Connection and login fields:

Claim and group fields:

If email is present in scopes, the selected email Claim must be a string and email_verified must be a Boolean in the merged response. Missing either value causes login to fail.

#Login, Update, and Delete Behavior

• OIDC users are created or updated after a successful browser login. OIDC does not provide LDAP-style manual or scheduled user synchronization.
• After updating the username mapping, start a new browser session and log in again to verify the updated user.
• Deleting the Connector through ACP without cleanup retains source users and marks them invalid.
• Selecting Clean up IDP users and User Groups deletes the generated source users and the managed Secret with the Connector.

Use the ACP console action or ACP product API for deletion. Deleting the underlying Connector custom resource directly with kubectl bypasses the tested ACP user-invalidation and cleanup behavior.

#Logout Behavior

In the validated current flow, ACP logout ended the ACP session and returned the browser to the ACP IDP chooser. Selecting the same OIDC entry again reused the still-active upstream session and signed the user in without another credential prompt. ACP logout therefore does not prove that the upstream session has ended.

The tested flow did not use the configured Logout URL as a browser redirect. Leave this field empty and validate upstream session termination separately when the customer's security requirements require it.

#Troubleshoot by Stage

For callback and user-mapping evidence, inspect the current ACP login component logs:

kubectl -n cpaas-system logs deployment/apollo --since=10m