Skip to content

Commit

Permalink
Merge pull request #297 from michael-doubez/jws-signing-verification
Browse files Browse the repository at this point in the history
Add JWKS parameters for verifying web token signatures
  • Loading branch information
michael-doubez committed Apr 20, 2024
2 parents 12ab2e3 + 9442607 commit 5ad9932
Show file tree
Hide file tree
Showing 13 changed files with 474 additions and 26 deletions.
6 changes: 6 additions & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
# Text by default
* text=auto

# Images
*.jpg binary
*.png binary
96 changes: 90 additions & 6 deletions docs/configuration/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,15 +10,94 @@ There are specifics instructions for well known providers:
* [Google Provider](GOOGLE.md)
* [Gitlab Provider](GITLAB.md)

This page contains the reference of plugin's configuration.

## Provider configuration

The OpenID Conenct spec describes a well known configuration location
The OpenID Connect spec describes a well known configuration location
which will also help discovering your settings
(<https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig>)

From 1.5 and onward the well known configuration location may be used to
populate the configuration simplifying the configuration greatly.
populate the configuration simplifying the configuration greatly.
The switch between modes is controled by the `automanualconfigure` 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 |

### 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.

| field | format | description |
| ----- | ------ | ----------- |
| wellKnownOpenIDConfigurationUrl | url | Providers' well-known configuration endpoint |
| overrideScopes | 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
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`.
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 |

### 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 |

### 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 |

## 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 |


## JCasC configuration reference

Expand All @@ -28,17 +107,21 @@ JCasC configuration can be defined with the following fields:
jenkins:
securityRealm:
oic:
# Endpoints
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>
# Credentials
clientId: <string>
clientSecret: <string:secret>
tokenAuthMethod: <string:enum>
# claims
scopes: <string:space separated words>
userNameField: <string:jmes path>
groupsFieldName: <string:jmes path>
fullNameFieldName: <string: jmes path>
Expand All @@ -51,9 +134,10 @@ jenkins:
disableSslVerification: <boolean>
nonceDisabled: <boolean>
pkceEnabled: <boolean>
disableTokenVerification: <boolean>
tokenFieldToCheckKey: <string:jmes path>
tokenFieldToCheckValue: string
# escape hatch
tokenFieldToCheckValue: <string>
# escape hatch
escapeHatchEnabled: <boolean>
escapeHatchUsername: escapeHatchUsername
escapeHatchSecret: <string:secret>
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@
/*
* The MIT License
*
* Copyright (c) 2024 JenkinsCI oic-auth-plugin developers
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*/
package org.jenkinsci.plugins.oic;

import com.google.api.client.auth.openidconnect.IdToken;
import com.google.api.client.auth.openidconnect.IdTokenVerifier;
import com.google.api.client.json.webtoken.JsonWebSignature;
import hudson.Util;
import java.io.IOException;

/**
* Extend IdTokenVerifier to verify UserInfo webtoken
*/
public class OicJsonWebTokenVerifier extends IdTokenVerifier {

/** Bypass Signature verification if no JWKS url configured */
private final boolean hasNoJwksServerUrl;

/** Payload indicating userInfo */
private static final IdToken.Payload NO_PAYLOAD = new IdToken.Payload();

/**
* Default verifier
*/
public OicJsonWebTokenVerifier() {
super();
hasNoJwksServerUrl = true;
}

Check warning on line 49 in src/main/java/org/jenkinsci/plugins/oic/OicJsonWebTokenVerifier.java

View check run for this annotation

ci.jenkins.io / Code Coverage

Not covered lines

Lines 47-49 are not covered by tests

/**
* Verifier with custom builder
*/
public OicJsonWebTokenVerifier(String jwksServerUrl, IdTokenVerifier.Builder builder) {
super(builder.setCertificatesLocation(jwksServerUrl));
hasNoJwksServerUrl = (Util.fixEmptyAndTrim(jwksServerUrl) == null);
}

/** Verify real idtoken */
public boolean verifyIdToken(IdToken idToken) throws IOException {
if (hasNoJwksServerUrl) {
/* avoid Google's certificate fallback mechanism */
return super.verifyPayload(idToken);
}
return verifyOrThrow(idToken);
}

/** Verify userinfo jwt token */
public boolean verifyUserInfo(JsonWebSignature userinfo) throws IOException {
if (hasNoJwksServerUrl) {
/* avoid Google's certificate fallback mechanism */
return true;
}
IdToken idToken = new IdToken(
userinfo.getHeader(),
NO_PAYLOAD, /* bypass verification of payload */
userinfo.getSignatureBytes(),
userinfo.getSignedContentBytes());
return verifyOrThrow(idToken);
}

/** hack: verify payload only if idtoken is not userinfo */
@Override
protected boolean verifyPayload(IdToken idToken) {
if (idToken.getPayload() == NO_PAYLOAD) {
return true;
}
return super.verifyPayload(idToken);
}
}

0 comments on commit 5ad9932

Please sign in to comment.