#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 initial integration. Use the YAML tab only when the returned username Claim must be selected explicitly, as described in 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.

#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.

#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 has no usable name Claim but does return preferred_username.

apiVersion: dex.coreos.com/v1
kind: Connector
id: corporate-oidc
name: Corporate OIDC
type: oidc
metadata:
  name: corporate-oidc
  namespace: cpaas-system
  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
    userNameKey: preferred_username

Replace the Issuer, credentials, and ACP address before submission. Do not add openid to scopes; the Connector adds it to the authorization request. Confirm through a real login that the selected userNameKey Claim is present and produces the expected ACP username.

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.

#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