Skip to content

Commit

Permalink
Merge pull request #417 from fcojfernandez/issues-416
Browse files Browse the repository at this point in the history 
Update CasC documentation
  • Loading branch information
@jtnord
jtnord authored Oct 8, 2024
2 parents d4eba97 + 462ebff commit b0ebf34
Showing 1 changed file with 66 additions and 53 deletions.
119 changes: 66 additions & 53 deletions docs/configuration/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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<br />- `auto`: activate automatic configuration <br />- `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<br />- `wellKnown`: activate discovery via well-known endpoint <br />- `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
Expand All @@ -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)<br />- `client_secret_basic`: for client id/secret as basic authentication user/pass<br />- `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)<br />- `client_secret_basic`: for client id/secret as basic authentication user/pass<br />- `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
Expand All @@ -108,36 +112,45 @@ JCasC configuration can be defined with the following fields:
jenkins:
securityRealm:
oic:
automanualconfigure: <string:enum>
# Automatic config of endpoint
wellKnownOpenIDConfigurationUrl: <url>
overrideScopes: <string:space separated words>
# Manual config of endpoint
tokenServerUrl: <url>
authorizationServerUrl: <url>
endSessionEndpoint: <url>
jwksServerUrl: <url>
scopes: <string:space separated words>
serverConfiguration:
# Automatic config of endpoint
wellKnown:
wellKnownOpenIDConfigurationUrl: <url>
scopesOverride: <string:space separated words>
# Manual config of endpoint
manual:
authorizationServerUrl: <url>
endSessionEndpoint: <url>
issuer: <string>
jwksServerUrl: <url>
tokenAuthMethod: <string:enum>
tokenServerUrl: <url>
scopes: <string:space separated words>
userInfoServerUrl: <url>
useRefreshTokens: <boolean>
# Credentials
clientId: <string>
clientSecret: <string:secret>
tokenAuthMethod: <string:enum>
# claims
userNameField: <string:jmes path>
groupsFieldName: <string:jmes path>
fullNameFieldName: <string: jmes path>
fullNameFieldName: <string:jmes path>
emailFieldName: <string:jmes path>
# advanced configuration
logoutFromOpenidProvider: <boolean>
rootURLFromRequest: <boolean>
sendScopesInTokenRequest: <boolean>
postLogoutRedirectUrl: <url>
# Security
allowTokenAccessWithoutOicSession: <boolean>
allowedTokenExpirationClockSkewSeconds: <integer>
disableSslVerification: <boolean>
nonceDisabled: <boolean>
pkceEnabled: <boolean>
disableTokenVerification: <boolean>
tokenFieldToCheckKey: <string:jmes path>
tokenFieldToCheckValue: <string>
tokenExpirationCheckDisabled: <boolean>
# escape hatch
escapeHatchEnabled: <boolean>
escapeHatchUsername: escapeHatchUsername
Expand Down

0 comments on commit b0ebf34

Please sign in to comment.