ClientRegistration API for AppSSO

In Application Single Sign-On (commonly called AppSSO), ClientRegistration is the request for client credentials for an AuthServer.

ClientRegistration is created automatically during the process of claiming credentials. However, there is also the option of creating it manually.

It implements the Service Bindings ProvisionedService. The credentials are returned as a Service Bindings Secret.

A ClientRegistration must uniquely identify an AuthServer by using spec.authServerSelector. If it matches none, too many or a disallowed AuthServer, it does not get credentials. The other fields are for the configuration of the client on the AuthServer.

Spec

apiVersion: sso.apps.tanzu.vmware.com/v1alpha1
kind: ClientRegistration
metadata:
  name: ""
  namespace: ""
spec:
  authServerSelector: # required
    matchLabels: { }
  redirectURIs: # optional
    - ""
  scopes: # optional
    - name: ""
      description: ""
  displayName: "" # optional, must be between 2 and 32 chars in length
  authorizationGrantTypes: # optional
    - client_credentials
    - authorization_code
    - refresh_token
  clientAuthenticationMethod: "" # optional, values accepted are described in Client authentication methods section
  requireUserConsent: false # optional
status:
  authServerRef:
    apiVersion: ""
    issuerURI: ""
    kind: ""
    name: ""
    namespace: ""
  binding:
    name: ""
  clientID: ""
  clientSecretHelp: ""
  conditions:
    - lastTransitionTime: ""
      message: ""
      reason: ""
      status: "True" # or "False"
      type: ""
  observedGeneration: 0

Alternatively, you can interactively discover the spec with:

kubectl explain clientregistrations.sso.apps.tanzu.vmware.com

Scopes

The following scopes must be included for the issuance of identity tokens:

• openid must be included for the identity tokens to be issued.
• profile must be included so the custom-mapped claims are included in an issued identity token, for example, AuthServer.identityProviders[*].{openID,ldap,saml}.idToken.claims. For more information, see Identity token claims mapping.
• email must be included to retain the email and email_verified claims.
• address must be included to retain the address claim.
• phone must be included to retain the phone_number and phone_number_verified claims.
• roles must be included to retrieve the user role information from an upstream identity provider. For more information, see Configure authorization.

Client authentication methods

Client authentication methods supported by ClientRegistration resource are:

• client_secret_basic: HTTP header based client authentication (default).
• client_secret_post: HTTP POST body based client authentication.
• none: No client authentication. Required for public clients. For more information, see Public clients and CORS.

Status & conditions

The .status subresource helps you to learn about your client credentials, the matched AuthServer and to troubleshoot issues.

.status.authServerRef identifies the successfully matched AuthServer and its issuer URI.

.status.binding.name is the name of the Service Bindings Secret which contains the client credentials.

.status.conditions documents each step in the reconciliation:

• Valid: Is the spec valid?
• AuthServerResolved: Has the targeted AuthServer been resolved?
• ClientSecretResolved: Has the client secret been resolved?
• ServiceBindingSecretApplied: Has the Service Bindings Secret with the client credentials been applied?
• AuthServerConfigured: Has the resolved AuthServer been configured with the client?
• Ready: whether all the previous conditions are “True”

The super condition Ready denotes a fully successful reconciliation of a given ClientRegistration.

If everything goes well you will see something like this:

status:
  authServerRef:
    apiVersion: sso.apps.tanzu.vmware.com/v1alpha1
    issuerURI: http://authserver-sample.default
    kind: AuthServer
    name: authserver-sample
    namespace: default
  binding:
    name: clientregistration-sample
  clientID: default_clientregistration-sample
  clientSecretHelp: 'Find your clientSecret: ''kubectl get secret clientregistration-sample --namespace default'''
  conditions:
    - lastTransitionTime: "2022-05-13T07:56:41Z"
      message: ""
      reason: Updated
      status: "True"
      type: AuthServerConfigured
    - lastTransitionTime: "2022-05-13T07:56:40Z"
      message: ""
      reason: Resolved
      status: "True"
      type: AuthServerResolved
    - lastTransitionTime: "2022-05-13T07:56:40Z"
      message: ""
      reason: ResolvedFromBindingSecret
      status: "True"
      type: ClientSecretResolved
    - lastTransitionTime: "2022-05-13T07:56:41Z"
      message: ""
      reason: Ready
      status: "True"
      type: Ready
    - lastTransitionTime: "2022-05-13T07:56:40Z"
      message: ""
      reason: Applied
      status: "True"
      type: ServiceBindingSecretApplied
    - lastTransitionTime: "2022-05-13T07:56:40Z"
      message: ""
      reason: Valid
      status: "True"
      type: Valid
  observedGeneration: 1

Example

apiVersion: sso.apps.tanzu.vmware.com/v1alpha1
kind: ClientRegistration
metadata:
  name: my-client-registration
  namespace: app-team
spec:
  displayName: "My sample app"
  authServerSelector:
    matchLabels:
      for: app-team
      ldap: "true"
  redirectURIs:
    - "https://127.0.0.1:8080/authorized"
    - "https://my-application.com/authorized"
  requireUserConsent: false
  clientAuthenticationMethod: client_secret_basic
  authorizationGrantTypes:
    - "authorization_code"
    - "refresh_token"
  scopes:
    - name: "openid"
      description: "To indicate that the application intends to use OIDC to verify the user's identity"
    - name: "email"
      description: "The user's email"
    - name: "profile"
      description: "The user's profile information"

The client is registered with the authorization server with the given spec. The resulting client credentials are available in a Secret that the ClientRegistration owns.

apiVersion: v1
kind: Secret
type: servicebinding.io/oauth2
metadata:
  name: my-client-registration
  namespace: app-team
data: # fields below are base64-decoded for display purposes only
  type: oauth2
  provider: appsso
  client-id: default_my-client-registration
  client-secret: c2VjcmV0 # auto-generated
  issuer-uri: https://appsso.example.com
  client-authentication-method: client_secret_basic
  scope: openid,email,profile
  authorization-grant-types: client_credentials,refresh_token