Applications/Clients must register with AppSSO to allow users to sign in with single sign on within a Kubernetes cluster. This registration will result in the creation of a Kubernetes secret
To do this, apply a
ClientRegistration to the appropriate Kubernetes cluster.
To confirm that the
ClientRegistration was successfully processed, check the status:
kubectl describe clientregistrations.sso.apps.tanzu.vmware.com <client-name>
It is also possible, but not recommended, to register clients statically while deploying AppSSO.
Note: It is recommended to register clients dynamically after AppSSO has been deployed. When registering a client statically, properties cannot be changed without triggering a rollout of AppSSO itself.
This guide will walk you through steps necessary to secure your deployed
Workload with AppSSO.
Before attempting to integrate your workload with AppSSO, please ensure that the following items are addressed:
v1.2.0or above is available on your cluster.
v0.11.6or above is available on your command line.
v1.0.0-beta.5or above is available on your cluster.
AppSSO and your Workload need to establish a bidirectional relationship: AppSSO is aware of your Workload and your Workload is aware of AppSSO. How does that work?
The following sections elaborate on both of the concepts in detail.
Define a ClientRegistration resource for your Workload. Here is an example:
apiVersion: sso.apps.tanzu.vmware.com/v1alpha1 kind: ClientRegistration metadata: name: my-workload-client-registration namespace: my-workload-namespace spec: authServerSelector: matchLabels: # ask your Service Operator for labels to target an `AuthServer` authorizationGrantTypes: - client_credentials - authorization_code - refresh_token clientAuthenticationMethod: basic requireUserConsent: true redirectURIs: - "<MY_WORKLOAD_HOSTNAME>/redirect-back-uri" scopes: - name: openid
Once applied successfully, this resource will create the appropriate credentials for your Workload to consume. More on this in the next section.
Please refer to the ClientRegistration custom resource documentation page for additional details on schema and specification of the resource.
Once a ClientRegistration resource has been defined, you can now create a service resource claim by using Tanzu CLI:
tanzu service claim create my-client-claim \ --namespace my-workload-namespace \ --resource-api-version sso.apps.tanzu.vmware.com/v1alpha1 \ --resource-kind ClientRegistration \ --resource-name my-workload-client-registration \ --resource-namespace my-workload-namespace
Alternatively, you may create the claim as a
ResourceClaim custom resource:
apiVersion: services.apps.tanzu.vmware.com/v1alpha1 kind: ResourceClaim metadata: name: my-client-claim namespace: my-workload-namespace spec: ref: apiVersion: sso.apps.tanzu.vmware.com/v1alpha1 kind: ClientRegistration name: my-workload-client-registration namespace: my-workload-namespace
Observe the status of the service resource claim by running
tanzu service claim list -n my-workload-namespace -o wide:
NAMESPACE NAME READY REASON CLAIM REF my-workload-namespace my-client-claim True services.apps.tanzu.vmware.com/v1alpha1:ResourceClaim:my-client-claim
The created service resource claim is now referable within a Workload:
apiVersion: carto.run/v1alpha1 kind: Workload metadata: labels: apps.tanzu.vmware.com/workload-type: web name: my-workload namespace: my-workload-namespace spec: source: git: ref: branch: main url: ssh://email@example.com/my-company/my-workload.git serviceClaims: - name: my-client ref: apiVersion: services.apps.tanzu.vmware.com/v1alpha1 kind: ResourceClaim name: my-client-claim
Alternatively, you can refer to your
ClientRegistration when deploying your workload with the
tanzu CLI. Like so
tanzu apps workload create my-workload \ --service-ref "my-client=services.apps.tanzu.vmware.com/v1alpha1:ResourceClaim:my-client-claim" \ # ...
What this service claim reference binding does under the hood is ensures that your Workload’s Pod is mounted with a volume containing the necessary credentials required by your application to become aware of AppSSO. Learn more about Service Bindings.
The credentials provided by the service claim are:
The above credentials are mounted onto your Workload’s Pod(s) as individual files at the following locations:
/bindings /<name-of-service-claim> /client-id /client-secret /issuer-uri /authorization-grant-types /client-authentication-method /scope
Taking our example from above, the location of credentials can be found at:
Given these auto-generated values, your Workload is now able to load them at runtime and bind to AppSSO at start-up time. Reading the values from the file system is left to the implementor as to the approach taken.