Return-Path: X-Original-To: archive-asf-public-internal@cust-asf2.ponee.io Delivered-To: archive-asf-public-internal@cust-asf2.ponee.io Received: from cust-asf.ponee.io (cust-asf.ponee.io [163.172.22.183]) by cust-asf2.ponee.io (Postfix) with ESMTP id F37F8200B27 for ; Wed, 22 Jun 2016 15:47:42 +0200 (CEST) Received: by cust-asf.ponee.io (Postfix) id F20A3160A36; Wed, 22 Jun 2016 13:47:42 +0000 (UTC) Delivered-To: archive-asf-public@cust-asf.ponee.io Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by cust-asf.ponee.io (Postfix) with SMTP id 768A2160A24 for ; Wed, 22 Jun 2016 15:47:41 +0200 (CEST) Received: (qmail 69299 invoked by uid 500); 22 Jun 2016 13:47:40 -0000 Mailing-List: contact commits-help@cxf.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@cxf.apache.org Delivered-To: mailing list commits@cxf.apache.org Received: (qmail 69290 invoked by uid 99); 22 Jun 2016 13:47:40 -0000 Received: from pnap-us-west-generic-nat.apache.org (HELO spamd1-us-west.apache.org) (209.188.14.142) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 22 Jun 2016 13:47:40 +0000 Received: from localhost (localhost [127.0.0.1]) by spamd1-us-west.apache.org (ASF Mail Server at spamd1-us-west.apache.org) with ESMTP id 331FDC3226 for ; Wed, 22 Jun 2016 13:47:40 +0000 (UTC) X-Virus-Scanned: Debian amavisd-new at spamd1-us-west.apache.org X-Spam-Flag: NO X-Spam-Score: 0.371 X-Spam-Level: X-Spam-Status: No, score=0.371 tagged_above=-999 required=6.31 tests=[KAM_ASCII_DIVIDERS=0.8, KAM_LAZY_DOMAIN_SECURITY=1, RP_MATCHES_RCVD=-1.429] autolearn=disabled Received: from mx1-lw-eu.apache.org ([10.40.0.8]) by localhost (spamd1-us-west.apache.org [10.40.0.7]) (amavisd-new, port 10024) with ESMTP id VHFwb5T6Bdaf for ; Wed, 22 Jun 2016 13:47:37 +0000 (UTC) Received: from mailrelay1-us-west.apache.org (mailrelay1-us-west.apache.org [209.188.14.139]) by mx1-lw-eu.apache.org (ASF Mail Server at mx1-lw-eu.apache.org) with ESMTP id 86A765F3F2 for ; Wed, 22 Jun 2016 13:47:36 +0000 (UTC) Received: from svn01-us-west.apache.org (svn.apache.org [10.41.0.6]) by mailrelay1-us-west.apache.org (ASF Mail Server at mailrelay1-us-west.apache.org) with ESMTP id C0BE7E0069 for ; Wed, 22 Jun 2016 13:47:35 +0000 (UTC) Received: from svn01-us-west.apache.org (localhost [127.0.0.1]) by svn01-us-west.apache.org (ASF Mail Server at svn01-us-west.apache.org) with ESMTP id BFD063A031D for ; Wed, 22 Jun 2016 13:47:35 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r991192 - in /websites/production/cxf/content: cache/docs.pageCache docs/jax-rs-oidc.html Date: Wed, 22 Jun 2016 13:47:35 -0000 To: commits@cxf.apache.org From: buildbot@apache.org X-Mailer: svnmailer-1.0.9 Message-Id: <20160622134735.BFD063A031D@svn01-us-west.apache.org> archived-at: Wed, 22 Jun 2016 13:47:43 -0000 Author: buildbot Date: Wed Jun 22 13:47:35 2016 New Revision: 991192 Log: Production update by buildbot for cxf Modified: websites/production/cxf/content/cache/docs.pageCache websites/production/cxf/content/docs/jax-rs-oidc.html Modified: websites/production/cxf/content/cache/docs.pageCache ============================================================================== Binary files - no diff available. Modified: websites/production/cxf/content/docs/jax-rs-oidc.html ============================================================================== --- websites/production/cxf/content/docs/jax-rs-oidc.html (original) +++ websites/production/cxf/content/docs/jax-rs-oidc.html Wed Jun 22 13:47:35 2016 @@ -117,15 +117,17 @@ Apache CXF -- JAX-RS OIDC

 

+/*]]>*/

+
  • OIDC RP support +

    • Introduction

    OpenId Connect (OIDC) is an identity layer built on top of the OAuth2 protocol.

    When the user authentication is required the client application initiates one of OIDC Core flows and redirects this user to OIDC provider. The user gets redirected back to the client after the authentication, with the client application receiving IdToken. If Authorization Code Flow is used then IdToken is returned as part of the follow up code to access token exchange, and if Implicit Flow is used then IdToken is returned immediately.  It is very much like OAuth2 except that an extra IdToken parameter is returned.

    CXF ships OIDC Provider (IDP) and Relying Party (RP) utility code to make it easy for developers to create their own custom OIDC providers or have JAX-RS applications integrated with well-known 3rd party OIDC IDPs.

    This code relies heavily on CXF OAuth2 and CXF JOSE modules.

    Maven Dependencies

    CXF OIDC module
    <dependency>
@@ -133,7 +135,7 @@ div.rbtoc1466599622984 li {margin-left:
     <artifactId>cxf-rt-rs-security-sso-oidc</artifactId>
     <version>3.1.7</version>
 </dependency>
    -

    IdToken and UserInfo

    IdToken is a primary extension that OIDC makes to OAuth2. It provides a collection of claims describing the authenticated user. IdToken is a secured JWT token which is JWS-signed and/or JWE-encrypted by OIDC IDP.

    CXF provides org.apache.cxf.rs.security.oidc.common.IdToken.

    One way to populate it is to register a custom SubjectCreator with either OidcAuthorizationCodeService or OidcImplicitService. For example, Fediz OIDC uses the following SubjectCreator: it accesses a user principal prepared by Fediz Authenticators and creates IdToken by converting an already available SAML token to IdToken and sets it on OidcUserSubject. In other cases a us er principal may already have a prepared IdToken. 

    The other approach is to create IdToken in a custom OAuthDataProvider at the moment a code grant or access token is persisted. In this case IdToken will need to be populated first and then converted to either JWS or JWE sequence and saved as a grant or token "id_token" property: if it is a code flow then set it as a grant property at the moment the grant is persisted, if it is the implicit flow - set it as a token property at the moment the token is persisted. This approach is a bit more involved but creating a JWS or JWS IdToken representations with CXF JOSE is straightforward.   

    In general the way IdToken is created is container/implementation specific. Creating IdToken is the main requirement for integrating CXF OIDC code w ith the 3rd party container.

    Finally, IdTokenResponseFilter (used by AccessTokenService to complete the authorization code flow) or OidcImplicitService can ask IdTokenProvider to create IdToken at the moment it needs to be returned to the client application. 

    IdToken can provide enough information for the client application to work with the current user. However, the client can get more information about the user from OIDC UserInfo endpoint.

    CXF provides  org.apache.cxf.rs.security.oidc.common.UserInfo. One can create and set it at OidcUserSubject at the same time IdToken is created or let CXF OIDCUserInfo service create it as described below.

    OIDC IDP support

    Currently CXF OIDC IDP code provides JAX-RS services for supporting OIDC Authorization Code, Implicit and Hybrid flows. These services support all OIDC response types.

    Services for supporting UserInfo requests and returning IdToken signature verification keys are also shipped. 

    Authentication Services

    Authorization Code Flow

    OidcAuthorizationCodeService and AccessTokenService provides a support OIDC Authorization Code flow. OidcAuthorizationCodeService is a simple AuthorizationCodeGrantService extension which enforces OIDC specific constraints. 

    IdTokenResponseFilter (used by AccessTokenService) is where IdToken is actually added to the client response.

    Implicit Flow

    OidcImplicitService is a simple ImplicitGrantService extension which enforces OIDC specific constraints and also adds IdToken is actually added to the client response.

    Hybrid Flow

    OidcHybridService supports Hybrid Flow by delegating to both OidcImplicitService and OidcAuthorizationCodeService.

    UserInfo Endpoint

    < p>UserInfoService returns UserInfo. It checks UserInfoProvider first, next - OidcUserSubject, and finally it defaults to converting the existing IdToken to UserInfo.

    Note UserInfoService is accessed by a client which uses the access token issued to it during the user authentication process. Therefore this line enforces it - it will fail if the access token has not been successfully validated.

    JWK Keys Service

    OidcKeysService returns a JWK key set containing a public verification JWK key. By default only a public key is returned by the service can be configured for JWK key to include the corresponding 0; X509 certificate chain too.  Use this service if IdToken is signed by a private RSA or EC key for the client be able to fetch the verification keys without having to import them into local key stores.

    Fediz OIDC

    Fediz OIDC provides a reference integration between CXF OIDC IDP code and its authentication system. It has OIDC Core supported with a minimum amount of code and configuration.

    OIDC RP support

    Demos

    BigQuery demo service is OAuth2 client which relies on CXF OIDC RP code to support interacting with the user, redirecting the user to Google to authenticate, and validating IdToken returned from Google AccessTokenService alongside a new access token (OIDC Authorization Code Flow). The demo service uses IdToken to address the user correctly and the access token to access the user's resources as authorized by the user.

    BasicOidc demo service is not an OAuth2 client, but a basic JAX-RS server. This server works with an HTTP Browser client which uses Google script libraries to get IdToken from Google OIDC Authorization endpoint (OIDC Implicit flow). This browser client interacts with CXF OIDC RP code to get IdToken validated and then posts this token to the demo service. Demo service depends on CXF OIDC RP to have this IdToken easily accessible in its code

     

     

    +

    IdToken and UserInfo

    IdToken is a primary extension that OIDC makes to OAuth2. It provides a collection of claims describing the authenticated user. IdToken is a secured JWT token which is JWS-signed and/or JWE-encrypted by OIDC IDP.

    CXF provides org.apache.cxf.rs.security.oidc.common.IdToken.

    One way to populate it is to register a custom SubjectCreator with either OidcAuthorizationCodeService or OidcImplicitService. For example, Fediz OIDC uses the following SubjectCreator: it accesses a user principal prepared by Fediz Authenticators and creates IdToken by converting an already available SAML token to IdToken and sets it on OidcUserSubject. In other cases a us er principal may already have a prepared IdToken. 

    The other approach is to create IdToken in a custom OAuthDataProvider at the moment a code grant or access token is persisted. In this case IdToken will need to be populated first and then converted to either JWS or JWE sequence and saved as a grant or token "id_token" property: if it is a code flow then set it as a grant property at the moment the grant is persisted, if it is the implicit flow - set it as a token property at the moment the token is persisted. This approach is a bit more involved but creating a JWS or JWS IdToken representations with CXF JOSE is straightforward.   

    In general the way IdToken is created is container/implementation specific. Creating IdToken is the main requirement for integrating CXF OIDC code w ith the 3rd party container.

    Finally, IdTokenResponseFilter (used by AccessTokenService to complete the authorization code flow) or OidcImplicitService can ask IdTokenProvider to create IdToken at the moment it needs to be returned to the client application. 

    IdToken can provide enough information for the client application to work with the current user. However, the client can get more information about the user from OIDC UserInfo endpoint.

    CXF provides  org.apache.cxf.rs.security.oidc.common.UserInfo. One can create and set it at OidcUserSubject at the same time IdToken is created or let CXF OIDCUserInfo service create it as described below.

    OIDC IDP support

    Currently CXF OIDC IDP code provides JAX-RS services for supporting OIDC Authorization Code, Implicit and Hybrid flows. These services support all OIDC response types.

    Services for supporting UserInfo requests and returning IdToken signature verification keys are also shipped. 

    Authentication Services

    Authorization Code Flow

    OidcAuthorizationCodeService and AccessTokenService provides a support OIDC Authorization Code flow. OidcAuthorizationCodeService is a simple AuthorizationCodeGrantService extension which enforces OIDC specific constraints. For example, see this line.

    IdTokenResponseFilter (used by AccessTokenService) is where IdToken is actually added to the client response. For example, see this line.

    Implicit Flow

    OidcImplicitService is a simple ImplicitGrantService extension which enforces OIDC specific constraints and also adds IdToken is actually added to the client response. For example, see this line (Note on this case Implicit Flow is supported due to OidcHybridService extending OidcImplicitService).

    Hybrid Flow

    OidcHybridService supports Hybrid Flow by delegating to both OidcImplicitService and OidcAuthorizationCodeService. For example, see this line.

    UserInfo Endpoint

    UserInfoService returns UserInfo. It checks UserInfoProvider first, next - OidcUserSubject, and finally it defaults to converting the existing IdToken to UserInfo.

    Note UserInfoService is accessed by a client which uses the access token issued to it during the user authentication process. Therefore this line enforces it - it will fail if the access token has not been successfully validated. For example, see this line.

    JWK Keys Service

    OidcKeysService returns a JWK key set containing a public verification J WK key. By default only a public key is returned by the service can be configured for JWK key to include the corresponding  X509 certificate chain too.  Use this service if IdToken is signed by a private RSA or EC key for the client be able to fetch the verification keys without having to import them into local key stores.

    For example, see this line.

    Fediz OIDC Provider

    Fediz OIDC project provides a reference integration between CXF OIDC IDP code and its authentication system. It has OIDC Core supported with a minimum amount of code and configuration.

    It creates IdToken in a custom SubjectCreator as described above. Currently it depends one CXF Ehcache OAuthDataProvider OOB so no custom persistence code is needed. Beside that it provides a support for managing the client registrations. It registers OIDC services as JAX-RS endpoints.

    While some implementation details may change going forward (example, the alternative data provider may get introduced, etc), for the most part it shows that creating IdToken is what is really needed to get the container integrated with the CXF OIDC code.

    OIDC RP support

    OIDC RP client support is needed for the client application to redirect a user to OIDC IDP, get IdToken and validate it, optionally get UserInfo, and make both IdToken and UserInfo easily accessible to the client application code for it to be able to interact with the user.

    Demos

    BigQuery demo service is OAuth2 client which relies on CXF OIDC RP code to support interacting with the user, redirecting the user to Google to authenticate, and validating IdToken returned from Google AccessTokenService alongside a new access token (OIDC Authorization Cod e Flow). The demo service uses IdToken to address the user correctly and the access token to access the user's resources as authorized by the user.

    For example, the context is injected and used to get the access token and the user info. See the context with the comments on how to configure RP filters.

    BasicOidc demo service is not an OAuth2 client, but a basic JAX-RS server. This server works with an HTTP Browser client which uses Google script libraries to get IdToken from Google OIDC Authorization endpoint (OIDC Implicit flow). This browser client interacts with CXF OIDC RP code to get IdToken validated and then posts this token to the demo service. Demo service depends on CXF OIDC RP to have this IdToken easily accessible in it s code