diff --git a/docs/configuration/README.md b/docs/configuration/README.md index 3ccd0121..8f66421a 100644 --- a/docs/configuration/README.md +++ b/docs/configuration/README.md @@ -21,25 +21,25 @@ which will also help discovering your settings From 1.5 and onward the well known configuration location may be used to populate the configuration simplifying the configuration greatly. -The switch between modes is controled by the `automanualconfigure` field +The switch between modes is controled by the `serverConfiguration` field -| field | format | description | -| ----- | ------ | ----------- | -| automanualconfigure | enum | Crontols endpoint configuration mode
- `auto`: activate automatic configuration
- `manual`: activate manual configuration | -| clientId | string | Id of the openid client obtained from the provider | -| clientSecret | secret | Secret associated to the client | +| field | format | description | +|----------------------|---------|------------------------------------------------------------------------------------------------------------------------------------------------------| +| clientId | string | Id of the openid client obtained from the provider | +| clientSecret | secret | Secret associated to the client | +| serverConfiguration | select | Crontols endpoint configuration mode
- `wellKnown`: activate discovery via well-known endpoint
- `manual`: activate manual configuration | ### Automatic configuration In automatic mode, the [well-known](https://datatracker.ietf.org/doc/html/rfc5785) configuration endpoint is regularly fetched and parse to fill the fields required in manual configuration. By default, all scopes are requested -but this can be overriden by the `overrideScopes` config parameter. +but this can be overriden by the `scopesOverride` config parameter. -| field | format | description | -| ----- | ------ | ----------- | -| wellKnownOpenIDConfigurationUrl | url | Providers' well-known configuration endpoint | -| overrideScopes | string | Space separated list of scopes to request (default: request all) | +| field | format | description | +|---------------------------------|--------|------------------------------------------------------------------| +| wellKnownOpenIDConfigurationUrl | url | Providers' well-known configuration endpoint | +| scopesOverride | string | Space separated list of scopes to request (default: request all) | When configuring from the interface, the automatic mode will fill in the fields expected in manual mode. This can be useful for prefilling the @@ -48,56 +48,60 @@ fields but adapting the configuration of the endpoints. ### Manual configuration The manual configuration mut provide the authorization and token endpoints. -The scopes can be configured but default to `openid profile`. +The scopes can be configured but default to `openid email`. If the JWKS endpoint is configured, JWS' signatures will be verified (unless disabled). -| field | format | description | -| ----- | ------ | ----------- | -| automanualconfigure | enum | Always `manual` in manual mode | -| authorizationServerUrl | url | URL the user is redirected to at login | -| tokenServerUrl | url | URL used by jenkins to request the tokens | -| endSessionEndpoint | url | URL to logout from provider (used if activated) | -| jwksServerUrl | url | URL of provider's jws certificates (unused if disabled) | -| scopes | string | Space separated list of scopes to request (default: request all) | -| tokenAuthMethod | enum | method used for authenticating when requesting token(s)
- `client_secret_basic`: for client id/secret as basic authentication user/pass
- `client_secret_post`: for client id/secret sent in post request -| userInfoServerUrl | url | URL to get user's details | +| field | format | description | +|------------------------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| authorizationServerUrl | url | URL the user is redirected to at login | +| tokenServerUrl | url | URL used by jenkins to request the tokens | +| endSessionEndpoint | url | URL to logout from provider (used if activated) | +| jwksServerUrl | url | URL of provider's jws certificates (unused if disabled) | +| scopes | string | Space separated list of scopes to request (default: `openid email`) | +| tokenAuthMethod | enum | Method used for authenticating when requesting token(s)
- `client_secret_basic`: for client id/secret as basic authentication user/pass
- `client_secret_post`: for client id/secret sent in post request | +| userInfoServerUrl | url | URL to get user's details | +| useRefreshTokens | boolean | If server supports refresh tokens, make sure to specify any additional scopes required for refresh token support. | +| issuer | string | The expected received ID Token's issuer | ### Advanced configuration Providers have some variation in their implementation of OpenID Connect or some oddities they required. -| field | format | description | -| ----- | ------ | ----------- | -| logoutFromOpenidProvider | boolean | Enable the logout from provider when user logout from Jenkisn. | -| sendScopesInTokenRequest | boolean | Some providers expects scopes to be sent in token request | -| rootURLFromRequest | boolean | When computing Jenkins redirect, the root url is either deduced from configured root url or request | +| field | format | description | +|---------------------------|----------|-----------------------------------------------------------------------------------------------------| +| logoutFromOpenidProvider | boolean | Enable the logout from provider when user logout from Jenkisn. | +| sendScopesInTokenRequest | boolean | Some providers expects scopes to be sent in token request | +| rootURLFromRequest | boolean | When computing Jenkins redirect, the root url is either deduced from configured root url or request | ### Security configuration Most security feature are activated by default if possible. -| field | format | description | -| ----- | ------ | ----------- | -| disableSslVerification | boolean | disable SSL verification (in case of self signed certificates by example) | -| nonceDisabled | boolean | Disable nonce verification | -| pkceEnable | boolean | Enable PKCE challenge | -| disableTokenVerification | boolean | Disable IdToken and UserInfo verification (not recommended) | -| tokenFieldToCheckKey | jmespath | field(s) to check to authorize user | -| tokenFieldToCheckValue | string | tokenFieldToCheckValue expected value | +| field | format | description | +|----------------------------------------|-----------|-------------------------------------------------------------------------------------------------------------------------------| +| allowTokenAccessWithoutOicSession | boolean | Allows Jenkins API token based access even if the associated user has completly logged out from Jenkins and the OIC Provider | +| allowedTokenExpirationClockSkewSeconds | integer | Additional number of seconds to add to access token expiry time in case of clock sync issues | +| disableSslVerification | boolean | Disable SSL verification (in case of self signed certificates by example) | +| nonceDisabled | boolean | Disable nonce verification | +| pkceEnable | boolean | Enable PKCE challenge | +| disableTokenVerification | boolean | Disable IdToken and UserInfo verification (not recommended) | +| tokenFieldToCheckKey | jmespath | Field(s) to check to authorize user | +| tokenFieldToCheckValue | string | TokenFieldToCheckValue expected value | +| tokenExpirationCheckDisabled | boolean | Disable checking of token expiration | ## User information Content of idtoken or user info to use for identifying the user. They are called claims in OpenID Connect terminology. -| field | format | description | -| ----- | ------ | ----------- | -| userNameField | jmes path | claim to use as user login (default: `sub`) | -| fullNameFieldName | jmes path | claim to use as name of user | -| emailFieldName | jmes path | claim to use for populating user email | -| groupsFieldName |jmes path | groups the user belongs to | +| field | format | description | +|-------------------|-----------|---------------------------------------------| +| userNameField | jmes path | claim to use as user login (default: `sub`) | +| fullNameFieldName | jmes path | claim to use as name of user | +| emailFieldName | jmes path | claim to use for populating user email | +| groupsFieldName | jmes path | groups the user belongs to | ## JCasC configuration reference @@ -108,36 +112,45 @@ JCasC configuration can be defined with the following fields: jenkins: securityRealm: oic: - automanualconfigure: - # Automatic config of endpoint - wellKnownOpenIDConfigurationUrl: - overrideScopes: - # Manual config of endpoint - tokenServerUrl: - authorizationServerUrl: - endSessionEndpoint: - jwksServerUrl: - scopes: + serverConfiguration: + # Automatic config of endpoint + wellKnown: + wellKnownOpenIDConfigurationUrl: + scopesOverride: + # Manual config of endpoint + manual: + authorizationServerUrl: + endSessionEndpoint: + issuer: + jwksServerUrl: + tokenAuthMethod: + tokenServerUrl: + scopes: + userInfoServerUrl: + useRefreshTokens: # Credentials clientId: clientSecret: - tokenAuthMethod: # claims userNameField: groupsFieldName: - fullNameFieldName: + fullNameFieldName: emailFieldName: # advanced configuration logoutFromOpenidProvider: rootURLFromRequest: sendScopesInTokenRequest: + postLogoutRedirectUrl: # Security + allowTokenAccessWithoutOicSession: + allowedTokenExpirationClockSkewSeconds: disableSslVerification: nonceDisabled: pkceEnabled: disableTokenVerification: tokenFieldToCheckKey: tokenFieldToCheckValue: + tokenExpirationCheckDisabled: # escape hatch escapeHatchEnabled: escapeHatchUsername: escapeHatchUsername