{"id":22268103,"url":"https://github.com/curityio/spring-boot-openid-client-mtls","last_synced_at":"2025-07-03T00:05:34.622Z","repository":{"id":74437596,"uuid":"254129130","full_name":"curityio/spring-boot-openid-client-mtls","owner":"curityio","description":"An example on how to create an OpenID client with Spring Security that uses mutual TLS client authentication to retrieve the token.","archived":false,"fork":false,"pushed_at":"2024-08-21T08:21:25.000Z","size":2868,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-04T20:45:29.594Z","etag":null,"topics":["code-example","financial-grade","mutual-tls","oauth2","openid-connect","spring-boot","website"],"latest_commit_sha":null,"homepage":"https://curity.io/resources/learn/oidc-spring-boot-mtls-auth/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/curityio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-04-08T15:36:57.000Z","updated_at":"2025-02-26T06:01:53.000Z","dependencies_parsed_at":"2024-12-03T11:11:17.743Z","dependency_job_id":"84c49dbd-69ed-468f-a2c9-d1e8269d940d","html_url":"https://github.com/curityio/spring-boot-openid-client-mtls","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/curityio/spring-boot-openid-client-mtls","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/curityio%2Fspring-boot-openid-client-mtls","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/curityio%2Fspring-boot-openid-client-mtls/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/curityio%2Fspring-boot-openid-client-mtls/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/curityio%2Fspring-boot-openid-client-mtls/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/curityio","download_url":"https://codeload.github.com/curityio/spring-boot-openid-client-mtls/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/curityio%2Fspring-boot-openid-client-mtls/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263234944,"owners_count":23434918,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["code-example","financial-grade","mutual-tls","oauth2","openid-connect","spring-boot","website"],"created_at":"2024-12-03T11:11:06.622Z","updated_at":"2025-07-03T00:05:34.545Z","avatar_url":"https://github.com/curityio.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenID Client with Spring Boot and mutual TLS Client Authentication\n\n[![Quality](https://img.shields.io/badge/quality-demo-red)](https://curity.io/resources/code-examples/status/)\n[![Availability](https://img.shields.io/badge/availability-source-blue)](https://curity.io/resources/code-examples/status/)\n\nThis repository contains an example implementation that demonstrate how to use Spring Boot and Spring Security to create an OpenID client that authenticates to the Curity Identity Server using mutual TLS.\n\nThere are only two things to consider when configuring the client in the Curity Identity Server:\n\n* choose the authentication method `mutual tls` and make sure it uses the self-signed certificate created below. \n* register the following redirect uri for your client: `https://localhost:9443/login/oauth2/code/idsvr`. \n\nThe redirect uri is the path of the application where the Curity Identity Server will redirect to after the user was authenticated. In this case we assume that this example will be hosted on `localhost`. \n\n## Create a Self-Signed Server Certificate for HTTPS\nWe secure this client application with HTTPS on port `9443` and need a certificate for that. Since this is just an example we create a self-signed certificate. Do not use self-signed certificates in production environments.\n\n```bash\nkeytool -genkeypair -alias https -keyalg RSA -keysize 4096 -keystore server.p12 -storepass Secr3t -storetype pkcs12 -validity 10 -dname \"CN=localhost, OU=Example, O=Curity AB, C=SE\"\n```\nPlace the key store `server.p12` in `src/main/resources`. Update the application configuration file `src/main/resources/application.yml` to run HTTPS on port `9443`:\n\n```yaml\nserver:\n  port: 9443\n  ssl:\n    key-store: classpath:server.p12\n    key-store-password: Secr3t\n    key-store-type: pkcs12\n    key-store-alias: https\n```\n\u003e **Note**: The browser will not trust this self-signed server certificate. You may notice an `SSLHandshakeException` in the console when running this example. Make sure your browser trusts the certificate if you want to get rid of the error.\n    \n## Create a Self-Signed Certificate for MTLS\nFor mutual TLS client authentication to work you need a client certificate. Create a Java keystore with the self-signed certificate.\n\n```bash\nkeytool -genkeypair -alias demo-client -keyalg RSA -keysize 4096 -keystore demo-client.p12 -storepass Secr3t -storetype pkcs12 -validity 10 -dname \"CN=demo-client, OU=Example, O=Curity AB, C=SE\"\n```\n\nPlace the key store in `src/main/resources`. See [Configure Application](#configure-application) for details.\n\nExport the certificate and use it to configure the client at the Curity Identity Server. See [Curity Identity Server Configuration](#curity-identity-server-configuration).\n\n```bash\nkeytool -export -alias demo-client -keystore demo-client.p12 -storepass Secr3t -storetype pkcs12 -file demo-client.cer\n```\n\n## Curity Identity Server Configuration\nTo run this example you need to setup some configurations in the Curity Identity Server. The easiest way is to download and install the sample configuration from [Curity Developer Portal](https://developer.curity.io/release/latest). This sample configuration already has an authentication profile and an OAuth profile that can be used with this example.\n\n1. Go to Token Service profile and make sure that `Mutual TLS` is enabled for `Client Authentication` on the `Client Settings` page of that profile.\n\n   ![image](./docs/images/profile-enable-mtls.png)\n \n1. Go to the `Clients` page of the profile and create a client called `demo-client`. If you use the sample configuration from [Curity Developer Portal](https://developer.curity.io/release/latest) create the `demo-client` client by copying the example client called `www`.\n   \n   ![image](./docs/images/duplicate-client.png)\n   \n1. This new client (accessible from `Token Service -\u003e Clients -\u003e demo-client -\u003e Edit Client`) uses mutual TLS for client authentication. \n   * Choose `mutual-tls` from the list of authentication methods.\n   * Select `Trust by a pinned client certificate`.\n   * Click `Create` to upload a client certificate.\n\n   ![image](./docs/images/client-authentication-method.png) \n\n1. Select the client certificate that you created [above](#create-a-self-signed-certificate). Give the newly created Client Trust Store the name `demo_client` and confirm the settings.\n   \n   ![image](./docs/images/new-client-trust-store.png) \n   \n   ![image](./docs/images/client-authentication-method-cert.png) \n   \n1. Continue with the `Capabilities` section for the `demo-client`. Make sure that the list contains at least the `Code Flow` capability.\n   \n   ![image](./docs/images/client-capabilities.png)\n   \n1. Update the `Redirect URIs` setting for the `demo-client`. The redirect URI should be `https://localhost:9443/login/oauth2/code/idsvr`.\n   \n   ![image](./docs/images/client-redirect-uri.png)\n   \n1. Finally, allow Client Authentication for the Token Endpoint. Go to Token Service profile and select `Endpoints`. Look for the `token-service-token` endpoint and set `Client Authentication` to `allowed`.\n \n   ![image](./docs/images/endpoints-client-auth.png)\n          \n1. Commit the changes and you are all setup.\n   \n\n## Configure Application\nUpdate the client registration and provider in `application.yml` to fit your setup. If you followed the instructions in [Curity Identity Server Configuration](#curity-identity-server-configuration) you do not need to change anything.\n\n```yaml\nspring:\n  security:\n    oauth2:\n      client:\n        registration:\n          idsvr:\n            client-name: Spring Boot OpenID Demo Client\n            client-id: demo-client\n            client-authentication-method: none\n            authorization-grant-type: authorization_code\n            redirect-uri: \"{baseUrl}/login/oauth2/code/{registrationId}\"\n            scope: openid\n        provider:\n          idsvr:\n            authorizationUri: https://localhost:8443/oauth/v2/oauth-authorize\n            tokenUri: https://localhost:8443/oauth/v2/oauth-token\n            jwkSetUri: https://localhost:8443/oauth/v2/oauth-anonymous/jwks\n```\n\nPlace the keystore created above in the `resources` folder and configure the SSL/TLS settings for the oauth client in `application.yml`:\n\n```yaml\ncustom:\n  client:\n    ssl:\n      key-store: demo-client.p12\n      key-store-password: Secr3t\n      key-store-type: pkcs12\n```\n\n## Trust Server Certificate\nThe application, in particular the underlying `WebClient` implementations that handle the requests to the token server namely to the Curity Identity Server, must trust the certificate provided by the server. Put the server certificate (`idsvr.cer`) in a trust store:\n\n```bash\nkeytool -import -file idsvr.cer -alias idsvr -keystore idsvr.p12 -storepass changeit -storetype pkcs12 -noprompt\n```\n\nPlace the trust store in the `resources` folder and update the SSL/TLS settings for the oauth client in `application.yml`:\n\n```yaml\ncustom:\n    client:\n      ssl: \n        trust-store: idsvr.p12\n        trust-store-password: changeit\n        trust-store-type: pkcs12\n```\n\n\u003e **Note** You may use a self signed certificate for the Curity Identity Server but make sure it is a valid certificate for the server name, i.e the certificate must include the hostname of the server in the subject or the list of subject alternative names. The client will otherwise reject the certificate and communication with the server will not work.\n\n## Run the Application\nTo start the application run \n\n```bash\n./gradlew bootRun\n```\n\nOpen `https://localhost:9443` in your browser. It will automatically start a login flow.\n\n## More Information\nMore information about OAuth 2.0, OpenID Connect and the Curity Identity Server can be found here:\n\n* [The Curity Identity Server](https://curity.io)\n* [OAuth 2.0](https://curity.io/resources/oauth/)\n* [OpenID Connect](https://curity.io/resources/openid-connect/)\n\nCheck out the related tutorial of this repository:\n* [OIDC Client with Mutual TLS Client Authentication](https://curity.io/resources/learn/oidc-spring-boot-mtls-auth/)\n\nRead up on [OAuth 2.0 Mutual TLS Client Authentication](https://curity.io/resources/learn/oauth-client-authentication-mutual-tls/)\n\n## Implementation Notes\nSpring Security OAuth 2.0 implementation does not support Mutual TLS Client Authentication out of the box (see [Issue #4498](https://github.com/spring-projects/spring-security/issues/4498) for status). As a result this example will only work with clients that run the \"Code Flow\". Further, any changes in the provider settings such as additional endpoints will most likely require adaption. \n\nHowever, most of the customization is required because of the trust store. If you don't mind a global trust in your application you may consider using JVM arguments instead of `custom.client.ssl.trust-store` in `application.yml` and run the application with the following command:\n\n```bash\n./gradlew bootRun -Djavax.net.ssl.trustStore=/full/path/to/localhost.truststore -Djavax.net.ssl.trustStorePassword=changeit\n```\n\n## Licensing\n\nThis software is copyright (C) 2020 Curity AB. It is open source software that is licensed under the [Apache 2 license](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcurityio%2Fspring-boot-openid-client-mtls","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcurityio%2Fspring-boot-openid-client-mtls","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcurityio%2Fspring-boot-openid-client-mtls/lists"}