Skip to content

Latest commit

 

History

History
2583 lines (1830 loc) · 127 KB

README.adoc

File metadata and controls

2583 lines (1830 loc) · 127 KB
Raw

API Reference

authentication.concierge.pinniped.dev/v1alpha1

Package v1alpha1 is the v1alpha1 version of the Pinniped concierge authentication API.

CertificateAuthorityDataSourceKind (string)

CertificateAuthorityDataSourceKind enumerates the sources for CA Bundles.

CertificateAuthorityDataSourceSpec

CertificateAuthorityDataSourceSpec provides a source for CA bundle used for client-side TLS verification.

Appears In:
Field Description

Kind configures whether the CA bundle is being sourced from a Kubernetes secret or a configmap.
Allowed values are "Secret" or "ConfigMap".
"ConfigMap" uses a Kubernetes configmap to source CA Bundles.
"Secret" uses Kubernetes secrets of type kubernetes.io/tls or Opaque to source CA Bundles.

name string

Name is the resource name of the secret or configmap from which to read the CA bundle.
The referenced secret or configmap must be created in the same namespace where Pinniped Concierge is installed.

key string

Key is the key name within the secret or configmap from which to read the CA bundle.
The value found at this key in the secret or configmap must not be empty, and must be a valid PEM-encoded
certificate bundle.

JWTAuthenticator

JWTAuthenticator describes the configuration of a JWT authenticator.

Upon receiving a signed JWT, a JWTAuthenticator will performs some validation on it (e.g., valid signature, existence of claims, etc.) and extract the username and groups from the token.

Appears In:
Field Description

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

Spec for configuring the authenticator.

Status of the authenticator.

JWTAuthenticatorPhase (string)

JWTAuthenticatorSpec

Spec for configuring a JWT authenticator.

Appears In:
Field Description

issuer string

Issuer is the OIDC issuer URL that will be used to discover public signing keys. Issuer is
also used to validate the "iss" JWT claim.

audience string

Audience is the required value of the "aud" JWT claim.

Claims allows customization of the claims that will be mapped to user identity
for Kubernetes access.

tls TLSSpec

TLS configuration for communicating with the OIDC provider.

JWTAuthenticatorStatus

Status of a JWT authenticator.

Appears In:
Field Description

conditions Condition array

Represents the observations of the authenticator’s current state.

Phase summarizes the overall status of the JWTAuthenticator.

JWTTokenClaims

JWTTokenClaims allows customization of the claims that will be mapped to user identity for Kubernetes access.

Appears In:
Field Description

groups string

Groups is the name of the claim which should be read to extract the user’s
group membership from the JWT token. When not specified, it will default to "groups".

username string

Username is the name of the claim which should be read to extract the
username from the JWT token. When not specified, it will default to "username".

TLSSpec

TLSSpec provides TLS configuration on various authenticators.

Field Description

certificateAuthorityData string

X.509 Certificate Authority (base64-encoded PEM bundle). If omitted, a default set of system roots will be trusted.

certificateAuthorityDataSource CertificateAuthorityDataSourceSpec

Reference to a CA bundle in a secret or a configmap.
Any changes to the CA bundle in the secret or configmap will be dynamically reloaded.

WebhookAuthenticator

WebhookAuthenticator describes the configuration of a webhook authenticator.

Field Description

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

Spec for configuring the authenticator.

Status of the authenticator.

WebhookAuthenticatorPhase (string)

WebhookAuthenticatorSpec

Spec for configuring a webhook authenticator.

Appears In:
Field Description

endpoint string

Webhook server endpoint URL.

tls TLSSpec

TLS configuration.

WebhookAuthenticatorStatus

Status of a webhook authenticator.

Appears In:
Field Description

conditions Condition array

Represents the observations of the authenticator’s current state.

Phase summarizes the overall status of the WebhookAuthenticator.

clientsecret.supervisor.pinniped.dev/clientsecret

Package clientsecret is the internal version of the Pinniped client secret API.

OIDCClientSecretRequest

OIDCClientSecretRequest can be used to update the client secrets associated with an OIDCClient.

Field Description

ObjectMeta ObjectMeta

OIDCClientSecretRequestSpec

Spec of the OIDCClientSecretRequest.

Field Description

GenerateNewSecret boolean

Request a new client secret to for the OIDCClient referenced by the metadata.name field.

RevokeOldSecrets boolean

Revoke the old client secrets associated with the OIDCClient referenced by the metadata.name field.

OIDCClientSecretRequestStatus

Status of the OIDCClientSecretRequest.

Field Description

GeneratedSecret string

The unencrypted OIDC Client Secret. This will only be shared upon creation and cannot be recovered if lost.

TotalClientSecrets integer

The total number of client secrets associated with the OIDCClient referenced by the metadata.name field.

clientsecret.supervisor.pinniped.dev/v1alpha1

Package v1alpha1 is the v1alpha1 version of the Pinniped client secret API.

OIDCClientSecretRequest

OIDCClientSecretRequest can be used to update the client secrets associated with an OIDCClient.

Field Description

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

OIDCClientSecretRequestSpec

Spec of the OIDCClientSecretRequest.

Field Description

generateNewSecret boolean

Request a new client secret to for the OIDCClient referenced by the metadata.name field.

revokeOldSecrets boolean

Revoke the old client secrets associated with the OIDCClient referenced by the metadata.name field.

OIDCClientSecretRequestStatus

Status of the OIDCClientSecretRequest.

Field Description

generatedSecret string

The unencrypted OIDC Client Secret. This will only be shared upon creation and cannot be recovered if lost.

totalClientSecrets integer

The total number of client secrets associated with the OIDCClient referenced by the metadata.name field.

config.concierge.pinniped.dev/v1alpha1

Package v1alpha1 is the v1alpha1 version of the Pinniped concierge configuration API.

CredentialIssuer

CredentialIssuer describes the configuration and status of the Pinniped Concierge credential issuer.

Appears In:
Field Description

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

Spec describes the intended configuration of the Concierge.

CredentialIssuerStatus describes the status of the Concierge.

CredentialIssuerFrontend

CredentialIssuerFrontend describes how to connect using a particular integration strategy.

Field Description

Type describes which frontend mechanism clients can use with a strategy.

tokenCredentialRequestInfo TokenCredentialRequestAPIInfo

TokenCredentialRequestAPIInfo describes the parameters for the TokenCredentialRequest API on this Concierge.
This field is only set when Type is "TokenCredentialRequestAPI".

impersonationProxyInfo ImpersonationProxyInfo

ImpersonationProxyInfo describes the parameters for the impersonation proxy on this Concierge.
This field is only set when Type is "ImpersonationProxy".

CredentialIssuerKubeConfigInfo

CredentialIssuerKubeConfigInfo provides the information needed to form a valid Pinniped-based kubeconfig using this credential issuer. This type is deprecated and will be removed in a future version.

Field Description

server string

The K8s API server URL.

certificateAuthorityData string

The K8s API server CA bundle.

CredentialIssuerSpec

CredentialIssuerSpec describes the intended configuration of the Concierge.

Appears In:
Field Description

impersonationProxy ImpersonationProxySpec

ImpersonationProxy describes the intended configuration of the Concierge impersonation proxy.

CredentialIssuerStatus

CredentialIssuerStatus describes the status of the Concierge.

Appears In:
Field Description

strategies CredentialIssuerStrategy array

List of integration strategies that were attempted by Pinniped.

Information needed to form a valid Pinniped-based kubeconfig using this credential issuer.
This field is deprecated and will be removed in a future version.

CredentialIssuerStrategy

CredentialIssuerStrategy describes the status of an integration strategy that was attempted by Pinniped.

Field Description

Type of integration attempted.

Status of the attempted integration strategy.

Reason for the current status.

message string

Human-readable description of the current status.

lastUpdateTime Time

When the status was last checked.

Frontend describes how clients can connect using this strategy.

FrontendType (string)

FrontendType enumerates a type of "frontend" used to provide access to users of a cluster.

ImpersonationProxyInfo

ImpersonationProxyInfo describes the parameters for the impersonation proxy on this Concierge.

Field Description

endpoint string

Endpoint is the HTTPS endpoint of the impersonation proxy.

certificateAuthorityData string

CertificateAuthorityData is the base64-encoded PEM CA bundle of the impersonation proxy.

ImpersonationProxyMode (string)

ImpersonationProxyMode enumerates the configuration modes for the impersonation proxy. Allowed values are "auto", "enabled", or "disabled".

ImpersonationProxyServiceSpec

ImpersonationProxyServiceSpec describes how the Concierge should provision a Service to expose the impersonation proxy.

Field Description

Type specifies the type of Service to provision for the impersonation proxy.

If the type is "None", then the "spec.impersonationProxy.externalEndpoint" field must be set to a non-empty
value so that the Concierge can properly advertise the endpoint in the CredentialIssuer’s status.

loadBalancerIP string

LoadBalancerIP specifies the IP address to set in the spec.loadBalancerIP field of the provisioned Service.
This is not supported on all cloud providers.

annotations object (keys:string, values:string)

Annotations specifies zero or more key/value pairs to set as annotations on the provisioned Service.

ImpersonationProxyServiceType (string)

ImpersonationProxyServiceType enumerates the types of service that can be provisioned for the impersonation proxy. Allowed values are "LoadBalancer", "ClusterIP", or "None".

ImpersonationProxySpec

ImpersonationProxySpec describes the intended configuration of the Concierge impersonation proxy.

Appears In:
Field Description

Mode configures whether the impersonation proxy should be started:
- "disabled" explicitly disables the impersonation proxy. This is the default.
- "enabled" explicitly enables the impersonation proxy.
- "auto" enables or disables the impersonation proxy based upon the cluster in which it is running.

Service describes the configuration of the Service provisioned to expose the impersonation proxy to clients.

externalEndpoint string

ExternalEndpoint describes the HTTPS endpoint where the proxy will be exposed. If not set, the proxy will
be served using the external name of the LoadBalancer service or the cluster service DNS name.

This field must be non-empty when spec.impersonationProxy.service.type is "None".

TLS contains information about how the Concierge impersonation proxy should serve TLS.

If this field is empty, the impersonation proxy will generate its own TLS certificate.

ImpersonationProxyTLSSpec

ImpersonationProxyTLSSpec contains information about how the Concierge impersonation proxy should serve TLS.

If CertificateAuthorityData is not provided, the Concierge impersonation proxy will check the secret for a field called "ca.crt", which will be used as the CertificateAuthorityData.

If neither CertificateAuthorityData nor ca.crt is provided, no CA bundle will be advertised for the impersonation proxy endpoint.

Field Description

certificateAuthorityData string

X.509 Certificate Authority (base64-encoded PEM bundle).
Used to advertise the CA bundle for the impersonation proxy endpoint.

secretName string

SecretName is the name of a Secret in the same namespace, of type kubernetes.io/tls, which contains
the TLS serving certificate for the Concierge impersonation proxy endpoint.

StrategyReason (string)

StrategyReason enumerates the detailed reason why a strategy is in a particular status.

StrategyStatus (string)

StrategyStatus enumerates whether a strategy is working on a cluster.

StrategyType (string)

StrategyType enumerates a type of "strategy" used to implement credential access on a cluster.

TokenCredentialRequestAPIInfo

TokenCredentialRequestAPIInfo describes the parameters for the TokenCredentialRequest API on this Concierge.

Field Description

server string

Server is the Kubernetes API server URL.

certificateAuthorityData string

CertificateAuthorityData is the base64-encoded Kubernetes API server CA bundle.

config.supervisor.pinniped.dev/v1alpha1

Package v1alpha1 is the v1alpha1 version of the Pinniped supervisor configuration API.

FederationDomain

FederationDomain describes the configuration of an OIDC provider.

Appears In:
Field Description

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

Spec of the OIDC provider.

Status of the OIDC provider.

FederationDomainIdentityProvider

FederationDomainIdentityProvider describes how an identity provider is made available in this FederationDomain.

Appears In:
Field Description

displayName string

DisplayName is the name of this identity provider as it will appear to clients. This name ends up in the
kubeconfig of end users, so changing the name of an identity provider that is in use by end users will be a
disruptive change for those users.

ObjectRef is a reference to a Pinniped identity provider resource. A valid reference is required.
If the reference cannot be resolved then the identity provider will not be made available.
Must refer to a resource of one of the Pinniped identity provider types, e.g. OIDCIdentityProvider,
LDAPIdentityProvider, ActiveDirectoryIdentityProvider.

Transforms is an optional way to specify transformations to be applied during user authentication and
session refresh.

FederationDomainPhase (string)

FederationDomainSecrets

FederationDomainSecrets holds information about this OIDC Provider’s secrets.

Field Description

JWKS holds the name of the corev1.Secret in which this OIDC Provider’s signing/verification keys are
stored. If it is empty, then the signing/verification keys are either unknown or they don’t
exist.

tokenSigningKey LocalObjectReference

TokenSigningKey holds the name of the corev1.Secret in which this OIDC Provider’s key for
signing tokens is stored.

stateSigningKey LocalObjectReference

StateSigningKey holds the name of the corev1.Secret in which this OIDC Provider’s key for
signing state parameters is stored.

stateEncryptionKey LocalObjectReference

StateSigningKey holds the name of the corev1.Secret in which this OIDC Provider’s key for
encrypting state parameters is stored.

FederationDomainSpec

FederationDomainSpec is a struct that describes an OIDC Provider.

Appears In:
Field Description

issuer string

Issuer is the OIDC Provider’s issuer, per the OIDC Discovery Metadata document, as well as the
identifier that it will use for the iss claim in issued JWTs. This field will also be used as
the base URL for any endpoints used by the OIDC Provider (e.g., if your issuer is
https://example.com/foo, then your authorization endpoint will look like
https://example.com/foo/some/path/to/auth/endpoint).

TLS specifies a secret which will contain Transport Layer Security (TLS) configuration for the FederationDomain.

identityProviders FederationDomainIdentityProvider array

IdentityProviders is the list of identity providers available for use by this FederationDomain.

An identity provider CR (e.g. OIDCIdentityProvider or LDAPIdentityProvider) describes how to connect to a server,
how to talk in a specific protocol for authentication, and how to use the schema of that server/protocol to
extract a normalized user identity. Normalized user identities include a username and a list of group names.
In contrast, IdentityProviders describes how to use that normalized identity in those Kubernetes clusters which
belong to this FederationDomain. Each entry in IdentityProviders can be configured with arbitrary transformations
on that normalized identity. For example, a transformation can add a prefix to all usernames to help avoid
accidental conflicts when multiple identity providers have different users with the same username (e.g.
"idp1:ryan" versus "idp2:ryan"). Each entry in IdentityProviders can also implement arbitrary authentication
rejection policies. Even though a user was able to authenticate with the identity provider, a policy can disallow
the authentication to the Kubernetes clusters that belong to this FederationDomain. For example, a policy could
disallow the authentication unless the user belongs to a specific group in the identity provider.

For backwards compatibility with versions of Pinniped which predate support for multiple identity providers,
an empty IdentityProviders list will cause the FederationDomain to use all available identity providers which
exist in the same namespace, but also to reject all authentication requests when there is more than one identity
provider currently defined. In this backwards compatibility mode, the name of the identity provider resource
(e.g. the Name of an OIDCIdentityProvider resource) will be used as the name of the identity provider in this
FederationDomain. This mode is provided to make upgrading from older versions easier. However, instead of
relying on this backwards compatibility mode, please consider this mode to be deprecated and please instead
explicitly list the identity provider using this IdentityProviders field.

FederationDomainStatus

FederationDomainStatus is a struct that describes the actual state of an OIDC Provider.

Appears In:
Field Description

Phase summarizes the overall status of the FederationDomain.

conditions Condition array

Conditions represent the observations of an FederationDomain’s current state.

Secrets contains information about this OIDC Provider’s secrets.

FederationDomainTLSSpec

FederationDomainTLSSpec is a struct that describes the TLS configuration for an OIDC Provider.

Appears In:
Field Description

secretName string

SecretName is an optional name of a Secret in the same namespace, of type kubernetes.io/tls, which contains
the TLS serving certificate for the HTTPS endpoints served by this FederationDomain. When provided, the TLS Secret
named here must contain keys named tls.crt and tls.key that contain the certificate and private key to use
for TLS.

Server Name Indication (SNI) is an extension to the Transport Layer Security (TLS) supported by all major browsers.

SecretName is required if you would like to use different TLS certificates for issuers of different hostnames.
SNI requests do not include port numbers, so all issuers with the same DNS hostname must use the same
SecretName value even if they have different port numbers.

SecretName is not required when you would like to use only the HTTP endpoints (e.g. when the HTTP listener is
configured to listen on loopback interfaces or UNIX domain sockets for traffic from a service mesh sidecar).
It is also not required when you would like all requests to this OIDC Provider’s HTTPS endpoints to
use the default TLS certificate, which is configured elsewhere.

When your Issuer URL’s host is an IP address, then this field is ignored. SNI does not work for IP addresses.

FederationDomainTransforms

FederationDomainTransforms defines identity transformations for an identity provider’s usage on a FederationDomain.

Field Description

Constants defines constant variables and their values which will be made available to the transform expressions.

Expressions are an optional list of transforms and policies to be executed in the order given during every
authentication attempt, including during every session refresh.
Each is a CEL expression. It may use the basic CEL language as defined in
https://github.com/google/cel-spec/blob/master/doc/langdef.md plus the CEL string extensions defined in
https://github.com/google/cel-go/tree/master/ext#strings.

The username and groups extracted from the identity provider, and the constants defined in this CR, are
available as variables in all expressions. The username is provided via a variable called username and
the list of group names is provided via a variable called groups (which may be an empty list).
Each user-provided constants is provided via a variable named strConst.varName for string constants
and strListConst.varName for string list constants.

The only allowed types for expressions are currently policy/v1, username/v1, and groups/v1.
Each policy/v1 must return a boolean, and when it returns false, no more expressions from the list are evaluated
and the authentication attempt is rejected.
Transformations of type policy/v1 do not return usernames or group names, and therefore cannot change the
username or group names.
Each username/v1 transform must return the new username (a string), which can be the same as the old username.
Transformations of type username/v1 do not return group names, and therefore cannot change the group names.
Each groups/v1 transform must return the new groups list (list of strings), which can be the same as the old
groups list.
Transformations of type groups/v1 do not return usernames, and therefore cannot change the usernames.
After each expression, the new (potentially changed) username or groups get passed to the following expression.

Any compilation or static type-checking failure of any expression will cause an error status on the FederationDomain.
During an authentication attempt, any unexpected runtime evaluation errors (e.g. division by zero) cause the
authentication attempt to fail. When all expressions evaluate successfully, then the (potentially changed) username
and group names have been decided for that authentication attempt.

Examples can optionally be used to ensure that the sequence of transformation expressions are working as
expected. Examples define sample input identities which are then run through the expression list, and the
results are compared to the expected results. If any example in this list fails, then this
identity provider will not be available for use within this FederationDomain, and the error(s) will be
added to the FederationDomain status. This can be used to help guard against programming mistakes in the
expressions, and also act as living documentation for other administrators to better understand the expressions.

FederationDomainTransformsConstant

FederationDomainTransformsConstant defines a constant variable and its value which will be made available to the transform expressions. This is a union type, and Type is the discriminator field.

Field Description

name string

Name determines the name of the constant. It must be a valid identifier name.

type string

Type determines the type of the constant, and indicates which other field should be non-empty.
Allowed values are "string" or "stringList".

stringValue string

StringValue should hold the value when Type is "string", and is otherwise ignored.

stringListValue string array

StringListValue should hold the value when Type is "stringList", and is otherwise ignored.

FederationDomainTransformsExample

FederationDomainTransformsExample defines a transform example.

Field Description

username string

Username is the input username.

groups string array

Groups is the input list of group names.

Expects is the expected output of the entire sequence of transforms when they are run against the
input Username and Groups.

FederationDomainTransformsExampleExpects

FederationDomainTransformsExampleExpects defines the expected result for a transforms example.

Field Description

username string

Username is the expected username after the transformations have been applied.

groups string array

Groups is the expected list of group names after the transformations have been applied.

rejected boolean

Rejected is a boolean that indicates whether authentication is expected to be rejected by a policy expression
after the transformations have been applied. True means that it is expected that the authentication would be
rejected. The default value of false means that it is expected that the authentication would not be rejected
by any policy expression.

message string

Message is the expected error message of the transforms. When Rejected is true, then Message is the expected
message for the policy which rejected the authentication attempt. When Rejected is true and Message is blank,
then Message will be treated as the default error message for authentication attempts which are rejected by a
policy. When Rejected is false, then Message is the expected error message for some other non-policy
transformation error, such as a runtime error. When Rejected is false, there is no default expected Message.

FederationDomainTransformsExpression

FederationDomainTransformsExpression defines a transform expression.

Field Description

type string

Type determines the type of the expression. It must be one of the supported types.
Allowed values are "policy/v1", "username/v1", or "groups/v1".

expression string

Expression is a CEL expression that will be evaluated based on the Type during an authentication.

message string

Message is only used when Type is policy/v1. It defines an error message to be used when the policy rejects
an authentication attempt. When empty, a default message will be used.

GrantType (string)

Appears In:

OIDCClient

OIDCClient describes the configuration of an OIDC client.

Appears In:
Field Description

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

Spec of the OIDC client.

Status of the OIDC client.

OIDCClientPhase (string)

Appears In:

OIDCClientSpec

OIDCClientSpec is a struct that describes an OIDCClient.

Appears In:
Field Description

allowedRedirectURIs RedirectURI array

allowedRedirectURIs is a list of the allowed redirect_uri param values that should be accepted during OIDC flows with this
client. Any other uris will be rejected.
Must be a URI with the https scheme, unless the hostname is 127.0.0.1 or ::1 which may use the http scheme.
Port numbers are not required for 127.0.0.1 or ::1 and are ignored when checking for a matching redirect_uri.

allowedGrantTypes GrantType array

allowedGrantTypes is a list of the allowed grant_type param values that should be accepted during OIDC flows with this
client.

Must only contain the following values:
- authorization_code: allows the client to perform the authorization code grant flow, i.e. allows the webapp to
authenticate users. This grant must always be listed.
- refresh_token: allows the client to perform refresh grants for the user to extend the user’s session.
This grant must be listed if allowedScopes lists offline_access.
- urn:ietf:params:oauth:grant-type:token-exchange: allows the client to perform RFC8693 token exchange,
which is a step in the process to be able to get a cluster credential for the user.
This grant must be listed if allowedScopes lists pinniped:request-audience.

allowedScopes Scope array

allowedScopes is a list of the allowed scopes param values that should be accepted during OIDC flows with this client.

Must only contain the following values:
- openid: The client is allowed to request ID tokens. ID tokens only include the required claims by default (iss, sub, aud, exp, iat).
This scope must always be listed.
- offline_access: The client is allowed to request an initial refresh token during the authorization code grant flow.
This scope must be listed if allowedGrantTypes lists refresh_token.
- pinniped:request-audience: The client is allowed to request a new audience value during a RFC8693 token exchange,
which is a step in the process to be able to get a cluster credential for the user.
openid, username and groups scopes must be listed when this scope is present.
This scope must be listed if allowedGrantTypes lists urn:ietf:params:oauth:grant-type:token-exchange.
- username: The client is allowed to request that ID tokens contain the user’s username.
Without the username scope being requested and allowed, the ID token will not contain the user’s username.
- groups: The client is allowed to request that ID tokens contain the user’s group membership,
if their group membership is discoverable by the Supervisor.
Without the groups scope being requested and allowed, the ID token will not contain groups.

tokenLifetimes OIDCClientTokenLifetimes

tokenLifetimes are the optional overrides of token lifetimes for an OIDCClient.

OIDCClientStatus

OIDCClientStatus is a struct that describes the actual state of an OIDCClient.

Appears In:
Field Description

phase summarizes the overall status of the OIDCClient.

conditions Condition array

conditions represent the observations of an OIDCClient’s current state.

totalClientSecrets integer

totalClientSecrets is the current number of client secrets that are detected for this OIDCClient.

OIDCClientTokenLifetimes

OIDCClientTokenLifetimes describes the optional overrides of token lifetimes for an OIDCClient.

Appears In:
Field Description

idTokenSeconds integer

idTokenSeconds is the lifetime of ID tokens issued to this client, in seconds. This will choose the lifetime of
ID tokens returned by the authorization flow and the refresh grant. It will not influence the lifetime of the ID
tokens returned by RFC8693 token exchange. When null, a short-lived default value will be used.
This value must be between 120 and 1,800 seconds (30 minutes), inclusive. It is recommended to make these tokens
short-lived to force the client to perform the refresh grant often, because the refresh grant will check with the
external identity provider to decide if it is acceptable for the end user to continue their session, and will
update the end user’s group memberships from the external identity provider. Giving these tokens a long life is
will allow the end user to continue to use a token while avoiding these updates from the external identity
provider. However, some web applications may have reasons specific to the design of that application to prefer
longer lifetimes.

RedirectURI (string)

Appears In:

Scope (string)

Appears In:

identity.concierge.pinniped.dev/identity

Package identity is the internal version of the Pinniped identity API.

ExtraValue (string array)

ExtraValue masks the value so protobuf can generate

Appears In:

KubernetesUserInfo

KubernetesUserInfo represents the current authenticated user, exactly as Kubernetes understands it. Copied from the Kubernetes token review API.

Appears In:
Field Description

User UserInfo

User is the UserInfo associated with the current user.

Audiences string array

Audiences are audience identifiers chosen by the authenticator.

UserInfo

UserInfo holds the information about the user needed to implement the user.Info interface.

Appears In:
Field Description

Username string

The name that uniquely identifies this user among all active users.

UID string

A unique value that identifies this user across time. If this user is
deleted and another user by the same name is added, they will have
different UIDs.

Groups string array

The names of groups this user is a part of.

Extra object (keys:string, values:ExtraValue)

Any additional information provided by the authenticator.

WhoAmIRequest

WhoAmIRequest submits a request to echo back the current authenticated user.

Appears In:
Field Description

ObjectMeta ObjectMeta

WhoAmIRequestSpec

Spec is always empty for a WhoAmIRequest.

Appears In:

WhoAmIRequestStatus

Status is set by the server in the response to a WhoAmIRequest.

Appears In:
Field Description

KubernetesUserInfo KubernetesUserInfo

The current authenticated user, exactly as Kubernetes understands it.

identity.concierge.pinniped.dev/v1alpha1

Package v1alpha1 is the v1alpha1 version of the Pinniped identity API.

ExtraValue (string array)

ExtraValue masks the value so protobuf can generate

Appears In:

KubernetesUserInfo

KubernetesUserInfo represents the current authenticated user, exactly as Kubernetes understands it. Copied from the Kubernetes token review API.

Appears In:
Field Description

user UserInfo

User is the UserInfo associated with the current user.

audiences string array

Audiences are audience identifiers chosen by the authenticator.

UserInfo

UserInfo holds the information about the user needed to implement the user.Info interface.

Appears In:
Field Description

username string

The name that uniquely identifies this user among all active users.

uid string

A unique value that identifies this user across time. If this user is
deleted and another user by the same name is added, they will have
different UIDs.

groups string array

The names of groups this user is a part of.

extra object (keys:string, values:ExtraValue)

Any additional information provided by the authenticator.

WhoAmIRequest

WhoAmIRequest submits a request to echo back the current authenticated user.

Appears In:
Field Description

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

WhoAmIRequestSpec

Spec is always empty for a WhoAmIRequest.

Appears In:

WhoAmIRequestStatus

Status is set by the server in the response to a WhoAmIRequest.

Appears In:
Field Description

kubernetesUserInfo KubernetesUserInfo

The current authenticated user, exactly as Kubernetes understands it.

idp.supervisor.pinniped.dev/v1alpha1

Package v1alpha1 is the v1alpha1 version of the Pinniped supervisor identity provider (IDP) API.

ActiveDirectoryIdentityProvider

ActiveDirectoryIdentityProvider describes the configuration of an upstream Microsoft Active Directory identity provider.

Field Description

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

Spec for configuring the identity provider.

Status of the identity provider.

ActiveDirectoryIdentityProviderBind

Field Description

secretName string

SecretName contains the name of a namespace-local Secret object that provides the username and
password for an Active Directory bind user. This account will be used to perform LDAP searches. The Secret should be
of type "kubernetes.io/basic-auth" which includes "username" and "password" keys. The username value
should be the full dn (distinguished name) of your bind account, e.g. "cn=bind-account,ou=users,dc=example,dc=com".
The password must be non-empty.

ActiveDirectoryIdentityProviderGroupSearch

Field Description

base string

Base is the dn (distinguished name) that should be used as the search base when searching for groups. E.g.
"ou=groups,dc=example,dc=com".
Optional, when not specified it will be based on the result of a query for the defaultNamingContext
(see https://docs.microsoft.com/en-us/windows/win32/adschema/rootdse).
The default behavior searches your entire domain for groups.
It may make sense to specify a subtree as a search base if you wish to exclude some groups
for security reasons or to make searches faster.

filter string

Filter is the ActiveDirectory search filter which should be applied when searching for groups for a user.
The pattern "{}" must occur in the filter at least once and will be dynamically replaced by the
value of an attribute of the user entry found as a result of the user search. Which attribute’s
value is used to replace the placeholder(s) depends on the value of UserAttributeForFilter.
E.g. "member={}" or "&(objectClass=groupOfNames)(member={})".
For more information about ActiveDirectory filters, see https://ldap.com/ldap-filters.
Note that the dn (distinguished name) is not an attribute of an entry, so "dn={}" cannot be used.
Optional. When not specified, the default will act as if the filter were specified as
"(&(objectClass=group)(member:1.2.840.113556.1.4.1941:={})".
This searches nested groups by default.
Note that nested group search can be slow for some Active Directory servers. To disable it,
you can set the filter to
"(&(objectClass=group)(member={})"

userAttributeForFilter string

UserAttributeForFilter specifies which attribute’s value from the user entry found as a result of
the user search will be used to replace the "{}" placeholder(s) in the group search Filter.
For example, specifying "uid" as the UserAttributeForFilter while specifying
"&(objectClass=posixGroup)(memberUid={})" as the Filter would search for groups by replacing
the "{}" placeholder in the Filter with the value of the user’s "uid" attribute.
Optional. When not specified, the default will act as if "dn" were specified. For example, leaving
UserAttributeForFilter unspecified while specifying "&(objectClass=groupOfNames)(member={})" as the Filter
would search for groups by replacing the "{}" placeholder(s) with the dn (distinguished name) of the user.

Attributes specifies how the group’s information should be read from each ActiveDirectory entry which was found as
the result of the group search.

skipGroupRefresh boolean

The user’s group membership is refreshed as they interact with the supervisor
to obtain new credentials (as their old credentials expire). This allows group
membership changes to be quickly reflected into Kubernetes clusters. Since
group membership is often used to bind authorization policies, it is important
to keep the groups observed in Kubernetes clusters in-sync with the identity
provider.

In some environments, frequent group membership queries may result in a
significant performance impact on the identity provider and/or the supervisor.
The best approach to handle performance impacts is to tweak the group query
to be more performant, for example by disabling nested group search or by
using a more targeted group search base.

If the group search query cannot be made performant and you are willing to
have group memberships remain static for approximately a day, then set
skipGroupRefresh to true. This is an insecure configuration as authorization
policies that are bound to group membership will not notice if a user has
been removed from a particular group until their next login.

This is an experimental feature that may be removed or significantly altered
in the future. Consumers of this configuration should carefully read all
release notes before upgrading to ensure that the meaning of this field has
not changed.

ActiveDirectoryIdentityProviderGroupSearchAttributes

Field Description

groupName string

GroupName specifies the name of the attribute in the Active Directory entries whose value shall become a group name
in the user’s list of groups after a successful authentication.
The value of this field is case-sensitive and must match the case of the attribute name returned by the ActiveDirectory
server in the user’s entry. E.g. "cn" for common name. Distinguished names can be used by specifying lower-case "dn".
Optional. When not specified, this defaults to a custom field that looks like "sAMAccountName@domain",
where domain is constructed from the domain components of the group DN.

ActiveDirectoryIdentityProviderPhase (string)

ActiveDirectoryIdentityProviderSpec

Spec for configuring an ActiveDirectory identity provider.

Field Description

host string

Host is the hostname of this Active Directory identity provider, i.e., where to connect. For example: ldap.example.com:636.

tls TLSSpec

TLS contains the connection settings for how to establish the connection to the Host.

Bind contains the configuration for how to provide access credentials during an initial bind to the ActiveDirectory server
to be allowed to perform searches and binds to validate a user’s credentials during a user’s authentication attempt.

UserSearch contains the configuration for searching for a user by name in Active Directory.

GroupSearch contains the configuration for searching for a user’s group membership in ActiveDirectory.

ActiveDirectoryIdentityProviderStatus

Status of an Active Directory identity provider.

Field Description

Phase summarizes the overall status of the ActiveDirectoryIdentityProvider.

conditions Condition array

Represents the observations of an identity provider’s current state.

ActiveDirectoryIdentityProviderUserSearch

Field Description

base string

Base is the dn (distinguished name) that should be used as the search base when searching for users.
E.g. "ou=users,dc=example,dc=com".
Optional, when not specified it will be based on the result of a query for the defaultNamingContext
(see https://docs.microsoft.com/en-us/windows/win32/adschema/rootdse).
The default behavior searches your entire domain for users.
It may make sense to specify a subtree as a search base if you wish to exclude some users
or to make searches faster.

filter string

Filter is the search filter which should be applied when searching for users. The pattern "{}" must occur
in the filter at least once and will be dynamically replaced by the username for which the search is being run.
E.g. "mail={}" or "&(objectClass=person)(uid={})". For more information about LDAP filters, see
https://ldap.com/ldap-filters.
Note that the dn (distinguished name) is not an attribute of an entry, so "dn={}" cannot be used.
Optional. When not specified, the default will be
'(&(objectClass=person)(!(objectClass=computer))(!(showInAdvancedViewOnly=TRUE))(|(sAMAccountName={}")(mail={})(userPrincipalName={})(sAMAccountType=805306368))'
This means that the user is a person, is not a computer, the sAMAccountType is for a normal user account,
and is not shown in advanced view only
(which would likely mean its a system created service account with advanced permissions).
Also, either the sAMAccountName, the userPrincipalName, or the mail attribute matches the input username.

Attributes specifies how the user’s information should be read from the ActiveDirectory entry which was found as
the result of the user search.

ActiveDirectoryIdentityProviderUserSearchAttributes

Field Description

username string

Username specifies the name of the attribute in Active Directory entry whose value shall become the username
of the user after a successful authentication.
Optional, when empty this defaults to "userPrincipalName".

uid string

UID specifies the name of the attribute in the ActiveDirectory entry which whose value shall be used to uniquely
identify the user within this ActiveDirectory provider after a successful authentication.
Optional, when empty this defaults to "objectGUID".

CertificateAuthorityDataSourceKind (string)

CertificateAuthorityDataSourceKind enumerates the sources for CA Bundles.

CertificateAuthorityDataSourceSpec

CertificateAuthorityDataSourceSpec provides a source for CA bundle used for client-side TLS verification.

Appears In:
Field Description

Kind configures whether the CA bundle is being sourced from a Kubernetes secret or a configmap.
Allowed values are "Secret" or "ConfigMap".
"ConfigMap" uses a Kubernetes configmap to source CA Bundles.
"Secret" uses Kubernetes secrets of type kubernetes.io/tls or Opaque to source CA Bundles.

name string

Name is the resource name of the secret or configmap from which to read the CA bundle.
The referenced secret or configmap must be created in the same namespace where Pinniped Supervisor is installed.

key string

Key is the key name within the secret or configmap from which to read the CA bundle.
The value found at this key in the secret or configmap must not be empty, and must be a valid PEM-encoded
certificate bundle.

GitHubAPIConfig

GitHubAPIConfig allows configuration for GitHub Enterprise Server

Field Description

host string

Host is required only for GitHub Enterprise Server.
Defaults to using GitHub’s public API ("github.com").
For convenience, specifying "github.com" is equivalent to specifying "api.github.com".
Do not specify a protocol or scheme since "https://" will always be used.
Port is optional. Do not specify a path, query, fragment, or userinfo.
Only specify domain name or IP address, subdomains (optional), and port (optional).
IPv4 and IPv6 are supported. If using an IPv6 address with a port, you must enclose the IPv6 address
in square brackets. Example: "[::1]:443".

tls TLSSpec

TLS configuration for GitHub Enterprise Server.
Note that this field should not be needed when using GitHub’s public API ("github.com").
However, if you choose to specify this field when using GitHub’s public API, you must
specify a CA bundle that will verify connections to "api.github.com".

GitHubAllowAuthenticationSpec

GitHubAllowAuthenticationSpec allows customization of who can authenticate using this IDP and how.

Field Description

organizations GitHubOrganizationsSpec

Organizations allows customization of which organizations can authenticate using this IDP.

GitHubAllowedAuthOrganizationsPolicy (string)

GitHubClaims

GitHubClaims allows customization of the username and groups claims.

Field Description

Username configures which property of the GitHub user record shall determine the username in Kubernetes.

Can be either "id", "login", or "login:id". Defaults to "login:id".

GitHub’s user login attributes can only contain alphanumeric characters and non-repeating hyphens,
and may not start or end with hyphens. GitHub users are allowed to change their login name,
although it is inconvenient. If a GitHub user changed their login name from "foo" to "bar",
then a second user might change their name from "baz" to "foo" in order to take the old
username of the first user. For this reason, it is not as safe to make authorization decisions
based only on the user’s login attribute.

If desired, an admin could configure identity transformation expressions on the Pinniped Supervisor’s
FederationDomain to further customize how these usernames are presented to Kubernetes.

Defaults to "login:id", which is the user login attribute, followed by a colon, followed by the unique and
unchanging integer ID number attribute. This blends human-readable login names with the unchanging ID value
from GitHub. Colons are not allowed in GitHub login attributes or ID numbers, so this is a reasonable
choice to concatenate the two values.

Groups configures which property of the GitHub team record shall determine the group names in Kubernetes.

Can be either "name" or "slug". Defaults to "slug".

GitHub team names can contain upper and lower case characters, whitespace, and punctuation (e.g. "Kube admins!").

GitHub team slugs are lower case alphanumeric characters and may contain dashes and underscores (e.g. "kube-admins").

Group names as presented to Kubernetes will always be prefixed by the GitHub organization name followed by a
forward slash (e.g. "my-org/my-team"). GitHub organization login names can only contain alphanumeric characters
or single hyphens, so the first forward slash / will be the separator between the organization login name and
the team name or slug.

If desired, an admin could configure identity transformation expressions on the Pinniped Supervisor’s
FederationDomain to further customize how these group names are presented to Kubernetes.

See the response schema for
[List teams for the authenticated user](https://docs.github.com/en/rest/teams/teams?apiVersion=2022-11-28#list-teams-for-the-authenticated-user).

GitHubClientSpec

GitHubClientSpec contains information about the GitHub client that this identity provider will use for web-based login flows.

Field Description

secretName string

SecretName contains the name of a namespace-local Secret object that provides the clientID and
clientSecret for an GitHub App or GitHub OAuth2 client.

This secret must be of type "secrets.pinniped.dev/github-client" with keys "clientID" and "clientSecret".

GitHubGroupNameAttribute (string)

GitHubGroupNameAttribute allows the user to specify which attribute from GitHub to use for the group names to present to Kubernetes. See the response schema for [List teams for the authenticated user](https://docs.github.com/en/rest/teams/teams?apiVersion=2022-11-28#list-teams-for-the-authenticated-user).

Appears In:

GitHubIdentityProvider

GitHubIdentityProvider describes the configuration of an upstream GitHub identity provider. This upstream provider can be configured with either a GitHub App or a GitHub OAuth2 App.

Right now, only web-based logins are supported, for both the pinniped-cli client and clients configured as OIDCClients.

Field Description

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

Spec for configuring the identity provider.

Status of the identity provider.

GitHubIdentityProviderPhase (string)

GitHubIdentityProviderSpec

GitHubIdentityProviderSpec is the spec for configuring an GitHub identity provider.

Field Description

githubAPI GitHubAPIConfig

GitHubAPI allows configuration for GitHub Enterprise Server

claims GitHubClaims

Claims allows customization of the username and groups claims.

allowAuthentication GitHubAllowAuthenticationSpec

AllowAuthentication allows customization of who can authenticate using this IDP and how.

Client identifies the secret with credentials for a GitHub App or GitHub OAuth2 App (a GitHub client).

GitHubIdentityProviderStatus

GitHubIdentityProviderStatus is the status of an GitHub identity provider.

Field Description

Phase summarizes the overall status of the GitHubIdentityProvider.

conditions Condition array

Conditions represents the observations of an identity provider’s current state.

GitHubOrganizationsSpec

Field Description

Allowed values are "OnlyUsersFromAllowedOrganizations" or "AllGitHubUsers".
Defaults to "OnlyUsersFromAllowedOrganizations".

Must be set to "AllGitHubUsers" if the allowed field is empty.

This field only exists to ensure that Pinniped administrators are aware that an empty list of
allowedOrganizations means all GitHub users are allowed to log in.

allowed string array

Allowed, when specified, indicates that only users with membership in at least one of the listed
GitHub organizations may log in. In addition, the group membership presented to Kubernetes will only include
teams within the listed GitHub organizations. Additional login rules or group filtering can optionally be
provided as policy expression on any Pinniped Supervisor FederationDomain that includes this IDP.

The configured GitHub App or GitHub OAuth App must be allowed to see membership in the listed organizations,
otherwise Pinniped will not be aware that the user belongs to the listed organization or any teams
within that organization.

If no organizations are listed, you must set organizations: AllGitHubUsers.

GitHubUsernameAttribute (string)

GitHubUsernameAttribute allows the user to specify which attribute(s) from GitHub to use for the username to present to Kubernetes. See the response schema for [Get the authenticated user](https://docs.github.com/en/rest/users/users?apiVersion=2022-11-28#get-the-authenticated-user).

Appears In:

LDAPIdentityProvider

LDAPIdentityProvider describes the configuration of an upstream Lightweight Directory Access Protocol (LDAP) identity provider.

Field Description

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

Spec for configuring the identity provider.

Status of the identity provider.

LDAPIdentityProviderBind

Field Description

secretName string

SecretName contains the name of a namespace-local Secret object that provides the username and
password for an LDAP bind user. This account will be used to perform LDAP searches. The Secret should be
of type "kubernetes.io/basic-auth" which includes "username" and "password" keys. The username value
should be the full dn (distinguished name) of your bind account, e.g. "cn=bind-account,ou=users,dc=example,dc=com".
The password must be non-empty.

LDAPIdentityProviderGroupSearch

Field Description

base string

Base is the dn (distinguished name) that should be used as the search base when searching for groups. E.g.
"ou=groups,dc=example,dc=com". When not specified, no group search will be performed and
authenticated users will not belong to any groups from the LDAP provider. Also, when not specified,
the values of Filter, UserAttributeForFilter, Attributes, and SkipGroupRefresh are ignored.

filter string

Filter is the LDAP search filter which should be applied when searching for groups for a user.
The pattern "{}" must occur in the filter at least once and will be dynamically replaced by the
value of an attribute of the user entry found as a result of the user search. Which attribute’s
value is used to replace the placeholder(s) depends on the value of UserAttributeForFilter.
For more information about LDAP filters, see https://ldap.com/ldap-filters.
Note that the dn (distinguished name) is not an attribute of an entry, so "dn={}" cannot be used.
Optional. When not specified, the default will act as if the Filter were specified as "member={}".

userAttributeForFilter string

UserAttributeForFilter specifies which attribute’s value from the user entry found as a result of
the user search will be used to replace the "{}" placeholder(s) in the group search Filter.
For example, specifying "uid" as the UserAttributeForFilter while specifying
"&(objectClass=posixGroup)(memberUid={})" as the Filter would search for groups by replacing
the "{}" placeholder in the Filter with the value of the user’s "uid" attribute.
Optional. When not specified, the default will act as if "dn" were specified. For example, leaving
UserAttributeForFilter unspecified while specifying "&(objectClass=groupOfNames)(member={})" as the Filter
would search for groups by replacing the "{}" placeholder(s) with the dn (distinguished name) of the user.

Attributes specifies how the group’s information should be read from each LDAP entry which was found as
the result of the group search.

skipGroupRefresh boolean

The user’s group membership is refreshed as they interact with the supervisor
to obtain new credentials (as their old credentials expire). This allows group
membership changes to be quickly reflected into Kubernetes clusters. Since
group membership is often used to bind authorization policies, it is important
to keep the groups observed in Kubernetes clusters in-sync with the identity
provider.

In some environments, frequent group membership queries may result in a
significant performance impact on the identity provider and/or the supervisor.
The best approach to handle performance impacts is to tweak the group query
to be more performant, for example by disabling nested group search or by
using a more targeted group search base.

If the group search query cannot be made performant and you are willing to
have group memberships remain static for approximately a day, then set
skipGroupRefresh to true. This is an insecure configuration as authorization
policies that are bound to group membership will not notice if a user has
been removed from a particular group until their next login.

This is an experimental feature that may be removed or significantly altered
in the future. Consumers of this configuration should carefully read all
release notes before upgrading to ensure that the meaning of this field has
not changed.

LDAPIdentityProviderGroupSearchAttributes

Field Description

groupName string

GroupName specifies the name of the attribute in the LDAP entries whose value shall become a group name
in the user’s list of groups after a successful authentication.
The value of this field is case-sensitive and must match the case of the attribute name returned by the LDAP
server in the user’s entry. E.g. "cn" for common name. Distinguished names can be used by specifying lower-case "dn".
Optional. When not specified, the default will act as if the GroupName were specified as "dn" (distinguished name).

LDAPIdentityProviderPhase (string)

LDAPIdentityProviderSpec

Spec for configuring an LDAP identity provider.

Appears In:
Field Description

host string

Host is the hostname of this LDAP identity provider, i.e., where to connect. For example: ldap.example.com:636.

tls TLSSpec

TLS contains the connection settings for how to establish the connection to the Host.

Bind contains the configuration for how to provide access credentials during an initial bind to the LDAP server
to be allowed to perform searches and binds to validate a user’s credentials during a user’s authentication attempt.

UserSearch contains the configuration for searching for a user by name in the LDAP provider.

GroupSearch contains the configuration for searching for a user’s group membership in the LDAP provider.

LDAPIdentityProviderStatus

Status of an LDAP identity provider.

Appears In:
Field Description

Phase summarizes the overall status of the LDAPIdentityProvider.

conditions Condition array

Represents the observations of an identity provider’s current state.

LDAPIdentityProviderUserSearch

Field Description

base string

Base is the dn (distinguished name) that should be used as the search base when searching for users.
E.g. "ou=users,dc=example,dc=com".

filter string

Filter is the LDAP search filter which should be applied when searching for users. The pattern "{}" must occur
in the filter at least once and will be dynamically replaced by the username for which the search is being run.
E.g. "mail={}" or "&(objectClass=person)(uid={})". For more information about LDAP filters, see
https://ldap.com/ldap-filters.
Note that the dn (distinguished name) is not an attribute of an entry, so "dn={}" cannot be used.
Optional. When not specified, the default will act as if the Filter were specified as the value from
Attributes.Username appended by "={}". When the Attributes.Username is set to "dn" then the Filter must be
explicitly specified, since the default value of "dn={}" would not work.

Attributes specifies how the user’s information should be read from the LDAP entry which was found as
the result of the user search.

LDAPIdentityProviderUserSearchAttributes

Field Description

username string

Username specifies the name of the attribute in the LDAP entry whose value shall become the username
of the user after a successful authentication. This would typically be the same attribute name used in
the user search filter, although it can be different. E.g. "mail" or "uid" or "userPrincipalName".
The value of this field is case-sensitive and must match the case of the attribute name returned by the LDAP
server in the user’s entry. Distinguished names can be used by specifying lower-case "dn". When this field
is set to "dn" then the LDAPIdentityProviderUserSearch’s Filter field cannot be blank, since the default
value of "dn={}" would not work.

uid string

UID specifies the name of the attribute in the LDAP entry which whose value shall be used to uniquely
identify the user within this LDAP provider after a successful authentication. E.g. "uidNumber" or "objectGUID".
The value of this field is case-sensitive and must match the case of the attribute name returned by the LDAP
server in the user’s entry. Distinguished names can be used by specifying lower-case "dn".

OIDCAuthorizationConfig

OIDCAuthorizationConfig provides information about how to form the OAuth2 authorization request parameters.

Field Description

additionalScopes string array

additionalScopes are the additional scopes that will be requested from your OIDC provider in the authorization
request during an OIDC Authorization Code Flow and in the token request during a Resource Owner Password Credentials
Grant. Note that the "openid" scope will always be requested regardless of the value in this setting, since it is
always required according to the OIDC spec. By default, when this field is not set, the Supervisor will request
the following scopes: "openid", "offline_access", "email", and "profile". See
https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims for a description of the "profile" and "email"
scopes. See https://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess for a description of the
"offline_access" scope. This default value may change in future versions of Pinniped as the standard evolves,
or as common patterns used by providers who implement the standard in the ecosystem evolve.
By setting this list to anything other than an empty list, you are overriding the
default value, so you may wish to include some of "offline_access", "email", and "profile" in your override list.
If you do not want any of these scopes to be requested, you may set this list to contain only "openid".
Some OIDC providers may also require a scope to get access to the user’s group membership, in which case you
may wish to include it in this list. Sometimes the scope to request the user’s group membership is called
"groups", but unfortunately this is not specified in the OIDC standard.
Generally speaking, you should include any scopes required to cause the appropriate claims to be the returned by
your OIDC provider in the ID token or userinfo endpoint results for those claims which you would like to use in
the oidcClaims settings to determine the usernames and group memberships of your Kubernetes users. See
your OIDC provider’s documentation for more information about what scopes are available to request claims.
Additionally, the Pinniped Supervisor requires that your OIDC provider returns refresh tokens to the Supervisor
from these authorization flows. For most OIDC providers, the scope required to receive refresh tokens will be
"offline_access". See the documentation of your OIDC provider’s authorization and token endpoints for its
requirements for what to include in the request in order to receive a refresh token in the response, if anything.
Note that it may be safe to send "offline_access" even to providers which do not require it, since the provider
may ignore scopes that it does not understand or require (see
https://datatracker.ietf.org/doc/html/rfc6749#section-3.3). In the unusual case that you must avoid sending the
"offline_access" scope, then you must override the default value of this setting. This is required if your OIDC
provider will reject the request when it includes "offline_access" (e.g. GitLab’s OIDC provider).

additionalAuthorizeParameters Parameter array

additionalAuthorizeParameters are extra query parameters that should be included in the authorize request to your
OIDC provider in the authorization request during an OIDC Authorization Code Flow. By default, no extra
parameters are sent. The standard parameters that will be sent are "response_type", "scope", "client_id",
"state", "nonce", "code_challenge", "code_challenge_method", and "redirect_uri". These parameters cannot be
included in this setting. Additionally, the "hd" parameter cannot be included in this setting at this time.
The "hd" parameter is used by Google’s OIDC provider to provide a hint as to which "hosted domain" the user
should use during login. However, Pinniped does not yet support validating the hosted domain in the resulting
ID token, so it is not yet safe to use this feature of Google’s OIDC provider with Pinniped.
This setting does not influence the parameters sent to the token endpoint in the Resource Owner Password
Credentials Grant. The Pinniped Supervisor requires that your OIDC provider returns refresh tokens to the
Supervisor from the authorization flows. Some OIDC providers may require a certain value for the "prompt"
parameter in order to properly request refresh tokens. See the documentation of your OIDC provider’s
authorization endpoint for its requirements for what to include in the request in order to receive a refresh
token in the response, if anything. If your provider requires the prompt parameter to request a refresh token,
then include it here. Also note that most providers also require a certain scope to be requested in order to
receive refresh tokens. See the additionalScopes setting for more information about using scopes to request
refresh tokens.

allowPasswordGrant boolean

allowPasswordGrant, when true, will allow the use of OAuth 2.0’s Resource Owner Password Credentials Grant
(see https://datatracker.ietf.org/doc/html/rfc6749#section-4.3) to authenticate to the OIDC provider using a
username and password without a web browser, in addition to the usual browser-based OIDC Authorization Code Flow.
The Resource Owner Password Credentials Grant is not officially part of the OIDC specification, so it may not be
supported by your OIDC provider. If your OIDC provider supports returning ID tokens from a Resource Owner Password
Credentials Grant token request, then you can choose to set this field to true. This will allow end users to choose
to present their username and password to the kubectl CLI (using the Pinniped plugin) to authenticate to the
cluster, without using a web browser to log in as is customary in OIDC Authorization Code Flow. This may be
convenient for users, especially for identities from your OIDC provider which are not intended to represent a human
actor, such as service accounts performing actions in a CI/CD environment. Even if your OIDC provider supports it,
you may wish to disable this behavior by setting this field to false when you prefer to only allow users of this
OIDCIdentityProvider to log in via the browser-based OIDC Authorization Code Flow. Using the Resource Owner Password
Credentials Grant means that the Pinniped CLI and Pinniped Supervisor will directly handle your end users' passwords
(similar to LDAPIdentityProvider), and you will not be able to require multi-factor authentication or use the other
web-based login features of your OIDC provider during Resource Owner Password Credentials Grant logins.
allowPasswordGrant defaults to false.

OIDCClaims

OIDCClaims provides a mapping from upstream claims into identities.

Field Description

groups string

Groups provides the name of the ID token claim or userinfo endpoint response claim that will be used to ascertain
the groups to which an identity belongs. By default, the identities will not include any group memberships when
this setting is not configured.

username string

Username provides the name of the ID token claim or userinfo endpoint response claim that will be used to
ascertain an identity’s username. When not set, the username will be an automatically constructed unique string
which will include the issuer URL of your OIDC provider along with the value of the "sub" (subject) claim from
the ID token.

additionalClaimMappings object (keys:string, values:string)

AdditionalClaimMappings allows for additional arbitrary upstream claim values to be mapped into the
"additionalClaims" claim of the ID tokens generated by the Supervisor. This should be specified as a map of
new claim names as the keys, and upstream claim names as the values. These new claim names will be nested
under the top-level "additionalClaims" claim in ID tokens generated by the Supervisor when this
OIDCIdentityProvider was used for user authentication. These claims will be made available to all clients.
This feature is not required to use the Supervisor to provide authentication for Kubernetes clusters, but can be
used when using the Supervisor for other authentication purposes. When this map is empty or the upstream claims
are not available, the "additionalClaims" claim will be excluded from the ID tokens generated by the Supervisor.

OIDCClient

OIDCClient contains information about an OIDC client (e.g., client ID and client secret).

Field Description

secretName string

SecretName contains the name of a namespace-local Secret object that provides the clientID and
clientSecret for an OIDC client. If only the SecretName is specified in an OIDCClient
struct, then it is expected that the Secret is of type "secrets.pinniped.dev/oidc-client" with keys
"clientID" and "clientSecret".

OIDCIdentityProvider

OIDCIdentityProvider describes the configuration of an upstream OpenID Connect identity provider.

Field Description

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

Spec for configuring the identity provider.

Status of the identity provider.

OIDCIdentityProviderPhase (string)

OIDCIdentityProviderSpec

OIDCIdentityProviderSpec is the spec for configuring an OIDC identity provider.

Appears In:
Field Description

issuer string

Issuer is the issuer URL of this OIDC identity provider, i.e., where to fetch
/.well-known/openid-configuration.

tls TLSSpec

TLS configuration for discovery/JWKS requests to the issuer.

authorizationConfig OIDCAuthorizationConfig

AuthorizationConfig holds information about how to form the OAuth2 authorization request
parameters to be used with this OIDC identity provider.

claims OIDCClaims

Claims provides the names of token claims that will be used when inspecting an identity from
this OIDC identity provider.

client OIDCClient

OIDCClient contains OIDC client information to be used used with this OIDC identity
provider.

OIDCIdentityProviderStatus

OIDCIdentityProviderStatus is the status of an OIDC identity provider.

Appears In:
Field Description

Phase summarizes the overall status of the OIDCIdentityProvider.

conditions Condition array

Represents the observations of an identity provider’s current state.

Parameter

Parameter is a key/value pair which represents a parameter in an HTTP request.

Field Description

name string

The name of the parameter. Required.

value string

The value of the parameter.

TLSSpec

TLSSpec provides TLS configuration for identity provider integration.

Field Description

certificateAuthorityData string

X.509 Certificate Authority (base64-encoded PEM bundle). If omitted, a default set of system roots will be trusted.

certificateAuthorityDataSource CertificateAuthorityDataSourceSpec

Reference to a CA bundle in a secret or a configmap.
Any changes to the CA bundle in the secret or configmap will be dynamically reloaded.

login.concierge.pinniped.dev/v1alpha1

Package v1alpha1 is the v1alpha1 version of the Pinniped login API.

ClusterCredential

ClusterCredential is the cluster-specific credential returned on a successful credential request. It contains either a valid bearer token or a valid TLS certificate and corresponding private key for the cluster.

Field Description

expirationTimestamp Time

ExpirationTimestamp indicates a time when the provided credentials expire.

token string

Token is a bearer token used by the client for request authentication.

clientCertificateData string

PEM-encoded client TLS certificates (including intermediates, if any).

clientKeyData string

PEM-encoded private key for the above certificate.

TokenCredentialRequest

TokenCredentialRequest submits an IDP-specific credential to Pinniped in exchange for a cluster-specific credential.

Field Description

metadata ObjectMeta

Refer to Kubernetes API documentation for fields of metadata.

TokenCredentialRequestSpec

Specification of a TokenCredentialRequest, expected on requests to the Pinniped API.

Field Description

token string

Bearer token supplied with the credential request.

Reference to an authenticator which can validate this credential request.

TokenCredentialRequestStatus

Status of a TokenCredentialRequest, returned on responses to the Pinniped API.

Field Description

credential ClusterCredential

A Credential will be returned for a successful credential request.

message string

An error message will be returned for an unsuccessful credential request.