SSO configuration with JSON Web Tokens

[Charlotte-Holt]

From LC: This is a new concept topic that should:

• [ ] Explain all the Liberty JWT features and when to use them (e.g., someone doing SAML can ignore this topic)
• [ ] Focus on what a developer needs to understand to use JWT - don't just document everything equally for the sake of being comprehensive.
• [ ] Provide a scenario of securely propagating authorization with requests to other microservices (JWT)

Info source: https://developer.ibm.com/wasdev/docs/using-signed-json-web-tokens-jwts-secure-microservices/ Proposed guide issue: https://github.com/OpenLiberty/guides-common/issues/131 Config examples w/ #636

[Rwalls1]

@lauracowen In regards to the Liberty JWT features, is there a reference for what those are. I may be overlooking something but I can't seem to identify them.

[lauracowen]

This is aimed at developers writing backend web services that need to be able to authorize requests to them (and requests from them to other web services) for information that is secured.

Start with the MicroProfile JWT capabilities (mpJwt feature) as that's the way we want/expect developers to go. Work through the JWT guide to learn about it: https://openliberty.io/guides/microprofile-jwt.html

The mpJwt feature depends on (automatically pulls in) the JWT feature, though you can also use the latter by itself (but start by focusing on developers using it through the MP JWT feature). There's a little bit about this (plus a full example you can take a look at) in this blog post: https://openliberty.io/blog/2019/08/29/securing-microservices-social-login-jwt.html

Talk to Bruce Tiffany about what is important for developers to know about in order to use JWT to secure their backend web services.

[Rwalls1]

@brutif Please review: https://draft-openlibertyio.mybluemix.net/docs/ref/general/#/docs/concept/sso-config-json.html.

[brutif]

@Rwalls1 looks good! Just a few minor suggestions-

claims by it --> claims in it.

trust the signature --> trust the issuer's signature

a secret key known to the OpenID Provider (OP) --> a secret key known to the creator of the JWT (anyone can create a JWT, not just OP's)

The net.oauth example used is ok, but that library is no longer maintained and has been removed from liberty. You might say something like

The following example shows the creation of a signed JWT with Java. Multiple open source libraries for creating and consuming JWT's exist. Liberty also provides API's to do this in the Jwt-1.0 feature.

assign user authentication to authorization servers --> delegate user authentication to remote identity providers (authorization usually happens at the app level, not the provider. The provider might say "This is Bruce, and Bruce is a manager" but it's the app that makes the authorization decision "managers can access payroll")

In the last part "Enabling identity management with OpenID Connect", I'm not sure if "roles" and "format" are the right words, but I'm also uncertain about what the right words might be. Maybe "OIDC format contains designated roles" --> OIDC authentication process involves specific roles". The word "flows" is used in the literature but it doesn't fit quite right here either.

"The user is the agent" --> "The end user is the party". (Agent isn't quite right. Bruce is the user, and Firefox is Bruce's agent.)

to an authorization server that implements OIDC. --> to an Open ID Connect provider

OpenID Provider --> OpenID Connect Provider (just switching to the formal name)

is an authorization server that implements OIDC, can authenticate a user, return claims --> can authenticate a user, either directly or by brokering to another provider. It can return claims

The Relying Party is the application --> The Relying Party is the application or container (in Liberty's case, apps don't have to worry about it, the container (Liberty) does it for them.)

The last one "OIDC standard format" I'll take a swing at. Typical OIDC authentication flow: A browser accesses a protected application and is redirected to the OP. The OP interacts with the user to authenticate them. After authentication, the user's browser is redirected back to the application. The application or it's container then contacts the OP and obtains a JWT containing claims about the user, and completes authentication and authorization. If successful, the user is granted access to the application. The application can access the claims that were sent in the JWT.

@chunlongliang-ibm knows the industry terms well, after you update, let's have him and I both take a look.

[lauracowen]

I just had a quick look too (I know you probably haven't done Bruce's changes yet). It looks really good thanks. A couple of comments:

• when you give the example SSO method, can you give Social Media Login instead of OpenID Connect? Social Media Login is based on OIDC but is simpler to configure etc and is what we want people to use. They can use OIDC directly but it's not nice and we'd rather guide people towards Social Media Login and customising that.
• in the identity management section towards the end of the topic, it's fine that you explain how OIDC works (assuming Bruce/Chunlong are fine with it) but add in that Social Media Login is based on ODIC and somehow emphasise that they should use that rather than the OIDC feature (I know OIDC refers to both the standard method and the name of the Liberty feature so I'll leave it with you - chat with @brutif about it). Basically we want people using Social Media feature where at all possible as it's easier.

Thank you

[Rwalls1]

@brutif Please review: https://draft-openlibertyio.mybluemix.net/docs/ref/general/#/docs/concept/sso-config-json.html. Due to other topics that are mentioning OIDC that we're also writing, I thought it would be better to avoid a detailed explanation of it in this topic and focus more on the importance of the MP-JWT feature. I've tried to include only the minimum information needed to understand the feature.

[brutif]

Hi, looks good, a few suggestions, transfer authentication and authorization information --> transfer authentication information (authorization is done by the app). Maybe you could say "transfer authentication and group membership information".

The MP-JWT feature is designed to verify claims between two services --> The MP-JWT feature is designed to verify claims between two services and to make accessing claim information easy for application developers.

"Mapping JAX-RS methods to MicroProfile JSON Web Tokens" - I'm not sure what you're trying to say here, but mp-jwt and jax-rs methods don't really intersect. Maybe "Using JSON Web Tokens with JAX-RS applications" - The MP-JWT specification defines how JWT's interact with Jave EE container security so they are easily used with JAX-RS applications. For more infomation see (link to mp-jwt specification.)

[chunlongliang-ibm]

about "Enabling identity management with SSO":

Although it is a valid scenario that Liberty explicitly request JWT from OpenID Connect server, it is very common that reverse proxy server (e.g., ISAM, Ping, API gateway, Istio service mesh) sends JWT to Liberty directly.

[Rwalls1]

@lauracowen Please review: https://draft-openlibertyio.mybluemix.net/docs/ref/general/#/docs/concept/sso-config-json.html

[ManasiGandhi]

@Rwalls1

The topic looks good. Just a few minor suggestions

• In this sentence 'Within this framework, the Social Login SSO method provides a simplified process that establishes user identity', instead of ' the Social Login SSO method ' say ' the Social Login with SSO method '.
• 'JWT use claims to transfer authentication and group membership information about a user between services', here say JWTs instead of JWT, or say JWT uses (I did a general Google search and found that JWT stands for JSON Web Token and not Tokens). Also here, 'The MP-JWT specification defines how JWT interact with Jave EE container security so they are easily used with JAX-RS applications.'
• ' The claims can verify who the user is, when the user requests were made, and any other types of information that the user agreed to you handling. 'Here, rephrase 'the user agreed to you handling' to 'the user agreed to be handled by you'

[Rwalls1]

@chunlongliang-ibm For your comment about "Enabling identity management with SSO", are you suggesting that a reverse proxy server, such as Istio, should be mentioned in some capacity there?

[Rwalls1]

@brutif Please review the latest updates: https://draft-openlibertyio.mybluemix.net/docs/ref/general/#/docs/concept/sso-config-json.html

[ManasiGandhi]

@Rwalls1 In 'Propagating user identity with JSON Web Tokens' add 'the' before JWT in 'After the user identity is established with an SSO method, such as Social Login, you can use JWT to propagate the identity to back-end services. '

Rest looks good.

[brutif]

@Rwalls1 looks good, one last suggestion - "To propagate user identity across different services with JWT, the identity must first be established with an SSO method. " Actually this is not true, things are a little more flexible. Might I suggest "To propagate user identity across different services with JWT, a JWT representing the user's identity can be obtained from an SSO method using OpenID Connect, or a JWT can be created programatically. (JWT's can be created no matter how we got the identity - oauth, ldap, saml, etc. Most SSO is actually not using openId Connect today, but openidConnect gives us a JWT by default, which is convenient.)

[Rwalls1]

@brutif Please review the latest update: https://draft-openlibertyio.mybluemix.net/docs/ref/general/#sso-config-json.html

[brutif]

@Rwalls1 this looks good! At the risk of irritating our SAML enthusiasts I'd change one word. The OpenID Connect (OIDC) standard for authentication provides the framework --> provides a framework.

[Rwalls1]

@brutif okay, you should be able to see that change now: https://draft-openlibertyio.mybluemix.net/docs/ref/general/#sso-config-json.html

[brutif]

@Rwalls1 thanks!

[Rwalls1]

@lauracowen Please review: https://draft-openlibertyio.mybluemix.net/docs/ref/general/#sso-config-json.html

[lauracowen]

Nice work, @Rwalls1 and @brutif Looks good. :)

Here's some feedback (nothing major so shouldn't take long to fix up):

• Where you link to oidc.html, can you instead link to https://draft-openlibertyio.mybluemix.net/docs/ref/feature/#openidConnectServer-1.0.html (but use the macro for that feature - ask Charlotte if you're not familiar with the format). Manasi is in the process of moving the material from the oidc.html topic to the generated feature doc and will be deleting oidc.html.
• Make clear that setting up Liberty as an OIDC provider is for use in a development environment - in production, you'd use a cloud-hosted provider instead (ie someone else would host the provider for you so you don't need to know how to set up Liberty as the provider. When you introduce the link, "For more information" isn't really explanatory enough about what they've find in that topic - it's not really more info about what you've just been talking about.
• Can you use "Social Media Login" not "Social Login" consistently (even use the macro for the feature where you're specifically referring to the Liberty feature name).
• "Propagating…" section
  • Could you briefly say what "claims" are? I think they're parts/lines/sections in the token? The text assumes the reader knows the structure of a token at this stage and claims seem a bit like magical things that are used to transfer authentication and then that they can verify who the user is etc. But it's not clear that they are lines of text inside a token (or whatever they specifically are - I can't remember exxactly).
  • "know that the content of the token isn’t altered since it was created" reads a bit oddly. I think it should be "know that the content of the token hasn’t been altered since it was created".
  • Don't abbreviate "MicroProfile JWT" to "MP-JWT". Just use the full "MicroProfile JWT" (which is already an abbreviation anyway). Unnecessary abbreviations are quicker to type but harder to read.
• "Securing…" section
  • Check with Charlotte about whether you should indicate that a link points to a guide or not (I can't remember what was decicded).
  • I think move the "For more info" link to the Eclipse newsletter to beneath the example JSON (have the lead-in sentence be the one that starts "The following example…").
• "Using JSON Web Tokens…" section
  • "Jave EE" is a typo but should maybe be "Jakarta EE" or, probably, "Java EE and Jakarta EE".
  • Don't link to the specification document - that isn't end-user developer documentation (it's for runtime implementation purposes). If there's specific info in there that we need here, we should include it here (or in another topic in the OL docs, as appropriate). If it's just for interest, the developer can go search for it; I don't think we should be recommending they go look there next. Instead, it would be more useful to end with a link to the JWT guide.

[brutif]

@lauracowen the oidc provider is used by customers in production, I don't think we want to alarm them by suggesting it's not suitable for that. You might say something like "For more information, see (link to liberty oidc provider) or (link to whatever other id provider it is we'd like them to use). Or you can just replace the oidc provider link if you want them to check out the public cloud provider.

[lauracowen]

@brutif Yes. I don't want to tell people it's not suitable - it's more that I don't want to make it look like they need to go through setting up an OL OIDC provider in order to use it. Could you help phrase something that says "commonly in the cloud, you can use the OIDC provider hosted in the cloud such as Red Hat SSO [or whatever it's called] to obtain JWTs; for local testing, you can easily set up an OIDC provider on OL "?

FWIW, we will provide some docs on doing things outside this assumed cloud-based scenario, it's just not an immediate focus and we want to keep the cloud-based microservices story clear for a start.

[brutif]

How about from: the Social Login SSO method provides a simplified process that establishes user identity. For more information, see Configuring Open Liberty as a single sign-on provider.

to: the Social Login SSO method provides a simplified process that establishes user identity by delegating authentication to a single sign on provider, such as Google or (insert favorite product here).

[Rwalls1]

@lauracowen @brutif Please review the latest update: https://draft-openlibertyio.mybluemix.net/docs/ref/general/#sso-config-json.html.

[brutif]

@Rwalls1 looks good!

[lauracowen]

minor request - can you change the filename to jwt instead of json?

[Rwalls1]

@lauracowen The filename has been updated: https://draft-openlibertyio.mybluemix.net/docs/ref/general/#sso-config-jwt.html.

[lauracowen]

This looks great, thanks for so much work on this.

• "The MicroProfile JWT feature contains required claims that must be specified to propagate user identity" - is "required" necessary in this sentence when it's followed by "that must be specified"? Alternatively, if "required claims" is the technical term and you feel it's important to use it in full here, then try phrasing it as "The MicroProfile JWT feature contains required claims, which must be specified to propagate user identity."
• "a name-value pair that consists of a" -> "a name-value pair which consists of a" (aside from making the sentence a bit easier to read without multiple "that", the name-value pair in this context does always consist of a claim name and value, so "which" is more accurate.

Aside from addressing those two comments, this looks ready to queue to publish. Thanks

[Rwalls1]

@lauracowen Please review the latest update: https://draft-openlibertyio.mybluemix.net/docs/ref/general/#sso-config-jwt.html

[lauracowen]

Thanks :)

[lauracowen]

Hi Richard,

Alasdair and I took a look at some of the SSO topics last night and we agreed we need to make some changes to how the SSO info is presented. We currently have too much info about the abstract concepts that people could better obtain elsewhere. I'm going to chat with Charlotte about it this afternoon but please can you hold off working on this topic in the meantime?

Thanks,

Laura

[lauracowen]

Superceded by #1676 so I'm closing this issue.