Authentication in Open Liberty

[Charlotte-Holt]

From LC: This is a new concept topic about authentication in Open Liberty. Authentication verifies who the user is. User ID and password (user registry - link to separate topic), SSO (LTPA, OpenID Connect, SAML, JWT, Social login, SPNEGO - link to separate topics because only one or two of them will be relevant to any given reader so they can ignore the ones they're not interested in). Users of apps running on OL can use their social media accounts (using OAuth and Open ID standards) to log into the apps. If multiple options are presented with a form to select which (give example screenshot to illustrate?). Out of the box, apps can be configured to enable users to use Facebook, Twitter, GitHub, LinkedIn, and Google, but others can be added. Once the user has authenticated, show how an app can find out who the person is.

The authentication topic in the KC provides a bit of an intro but it needs more. First introduce the concept of authentication on Open Liberty needs to be introduced first Introduce what JAAS (Java Authentication and Authorization Service) is and how it is used in authentication processes.

A diagram is needed but I don't know whether the one in this topic is a good one to use or not - probably needs updating for the context of microservices - ideally using one of our existing scenarios such as the system properties or the music store.

• https://www.ibm.com/support/knowledgecenter/SSD28V_liberty/com.ibm.websphere.wlp.core.doc/ae/cwlp_authentication.html
• https://www.ibm.com/support/knowledgecenter/SSD28V_liberty/com.ibm.websphere.wlp.core.doc/ae/cwlp_auth_app_client.html
• https://ibm.box.com/s/b9d5fililsqtwsb3yu8en3kqwet0ocsc
• https://ibm.box.com/s/thvnli5i160y63gk24ybs3ekvuj1p4h1 - presentation by Jim Mulvey
• SPNEGO config examples w/ Example config for spnego feature (SPNEGO) #954
• JWT config examples w/ Example config for JWT feature (MSSEC02) #636

[dmuelle]

@lauracowen I can't access either of the box notes above- the second appears to be expired and I don't have permission to the first- if another link is available can you share with me? The KC resources are helpful but I need to know what is specific to OL. I'm going to work through the Securing a web application guide, which should help as well.

[lauracowen]

Oops, sorry. The first was to the Intro to Security MP4 video and the second is the slides to that video. You can find them both in here: https://ibm.box.com/s/wokyhx7j1yr8883ehpdcnj2irzvao1xx (intranet only - sorry, the external links now expire quickly). The presentation was given to customers and anyone interested at the end of last year, I think.

[lauracowen]

Worth watching the intro to security video to get a general overview of what liberty security is about. Most of it is relevant to cloud deployments (though it doesn't specifically talk about that).

[dmuelle]

Draft up for review at
https://draft-openlibertyio.mybluemix.net/docs/ref/general/#authentication.html

Awaiting links to other docs (SSO topics) currently in development
Needs a diagram

[dmuelle]

Added suggested edits from Bruce Tiffany and put in a diagram mock-up. Diagram will need to be cleaned up once the content is approved

[Charlotte-Holt]

@dmuelle Peer review feedback:

• I really like the music example that you provided. Are you still planning to update this diagram?
• Link out to the Social Login feature the first time that it's mentioned.
• Could After authentication, an application can obtain a JSON Web Token (JWT) from the social media service or associated Open ID Connect provider, or create a new one. be changed to After authentication, an application can either obtain a JSON Web Token (JWT) from the social media service or associated Open ID Connect provider, or create a new one. I just got a little lost in that sentence when reading it.
• Link to the appSecurity feature
• After the sentence Open Liberty supports the following options for SSO authentication: I feel like maybe the SSO type headings should be another size smaller? Right now, I kind of expect a list of the same size, or maybe slightly larger, but the list of large headings following that sentence makes it feel like I'm missing something when I'm reading.
• In the heading, I think Open ID should be one word (OpenID)
• Add Open before Liberty in the Social media login section
• I think that Authentication may not need to be capitalized in JAAS Authentication with Open Liberty heading
• I think of needs to be added in Each LoginModule interface represents a particular type authentication service.
• Maybe rework the sentence JAAS is pluggable: new or updated authentication processes can be plugged in to an application without otherwise modifying the application itself. to not use a colon. It feels a little abrupt compared to the structure of the rest of the content.

I think you did a really nice job introducing what authentication is and framing it in the context of cloud-native microservice development (i.e., what it means for OL users).

[dmuelle]

Thanks for this review @Charlotte-Holt - the issues you've raised are addressed in this PR- #977
Note that some of the links in the SSO section (OIDC, SPEGNO, Social Login) will need to be updated from the gen doc to the concept topics once they are written

[lauracowen]

NIce! Thank you.

Couple of comments:

• Can you switch the order of the SSO authentication options in your list of links so that Social Media is first - that's the one we want people to use. OpenID Connect is the underlying tech which they can use directly but it's harder and we don't really want people going down that route, esp if social media login does what they need.
• "Users can implement a single account" - in this context, is users the developer or the end-user of the app? I think it's the developer so might be better to say "You can implement…"? Ah, no, maybe you mean end-users, in which case "Users can use a single account…?" Bascially, a website user wouldn't "implement an account", they'd log in or create an account. Maybe say "application (such as a website)" instead of "entity"?

[dmuelle]

Thanks @lauracowen - these issues are addressed in this PR- #981

[dmuelle]

Draft up for review at
https://draft-openlibertyio.mybluemix.net/docs/ref/general/#authentication.html

[dmuelle]

Updates per Ajay Reddy review:

• replace "application" references with "Open Liberty server" where appropriate
• add reference to token-based auth to intro section
• add LTPA cookies to SSO summary section
• remove JAAS auth section (make separate topic)

[lauracowen]

• Can you get someone to do a more Design-like version of the diagram? Is this the diagram that was finally agreed in that back-and-forth discussion a while back? I like it and I think it's nice and clear to me. Technically this shows both authentication and authorization - would it be worth/appropriate to include it in the Authorization topic too?
• UserRegistry interface - do you have a link to where they can find out more?
• could "that are hosted on the Open Liberty server" be just "that are hosted on Open Liberty"?
• "to authenticate users when they are accessing application servers." - users aren't really accessing application servers, they're accessing applications (I know technically they are but not from the user's perspective). Could it be instead "to authenticate users when they are accessing web applications." or something? Similarly, "securely transmit authentication-related data between servers" -> "securely transmit authentication-related data between services" or "...between web applications"? Maybe check with Ajay but we recommend a single service per server and the server is now almost hidden within the packaged up service - we don't need to be technically accurate as long as the concept makes sense, and it fits with the story we're telling - servers are a means to an end; it's the app/service that matters to developers.
• Can you check which heading level is used for the JAAS section heading - it looks huge!
• is it worth saying "Java Authentication and Authorization Service (JAAS), a Jakarta EE standard," or something similar? I think the point of this section is to show it's a standards-based approach, so that would make it clearer. At the moment, it reads a little like "And here's another technology OL uses to authenticate" and it's a bit unclear how this tech maps on to the previous techs discussed in this topic. Maybe needs an extra sentence or something?

Other than that, the topic looks great. Thank you.

[dmuelle]

• Can you get someone to do a more Design-like version of the diagram? yes- sent this mockup to Jay Cagle to get a proper diagram, waiting to hear back

• UserRegistry interface - this is pending the OL javadoc update, as we discussed via slack

• could "that are hosted on the Open Liberty server" be just "that are hosted on Open Liberty"? edited

• "to authenticate users when they are accessing application servers." changed to "web applications or services"

• Can you check which heading level is used for the JAAS section heading - it looks huge! oops, fixed

• is it worth saying "Java Authentication and Authorization Service (JAAS), a Jakarta EE standard," added that clause and changed "Open Liberty uses.." to "Open Liberty relies on.." to make it more clear JAAS is an underlying standard, as opposed to an auth mechanism

[lauracowen]

Great, thanks. There's not a lot we can do about the javadoc immediately but we can work on that separately. Aside from the diagram, I think this is good to go.

[dmuelle]

@lauracowen the new diagram from design is now on the draft site- let me know if it needs any further tweaking. Otherwise this should be ready to publish with the rest of the security topics?

https://draft-openlibertyio.mybluemix.net/docs/ref/general/#authentication.html

[lauracowen]

Pretty! :) I'm going to assume it's technically correct so if it's now there, I'm happy for this to be queued up with the rest of the security docs. Thanks

[dmuelle]

yup- this is the same one that Bruce et al signed off on in the one liberty slack discussion, just fitted and finished. I'll mark it ready to publish

[dmuelle]

Requested final peer review from @rw2513

[Rwalls1]

This is a well-written topic, I just have a couple comments:

• I think you could change “Authentication can be carried out” to “Authentication is completed” to be more concise.
• Double-check that all the links work properly, the links for “basic user registry” , "Lightweight Directory Access Protocol (LDAP) registry , “JSON Web Tokens”, “LTPA”, and "Security Assertion Markup Language (SAML 2.0)" didn’t seem to open correctly.

[dmuelle]

Thanks @Rwalls1 - I've updated the topic to fix that sentence and repair the broken links

https://draft-openlibertyio.mybluemix.net/docs/ref/general/#authentication-open-liberty.html

[brutif]

@dmuelle looks good!

[dmuelle]

New draft URL: https://draft-openlibertyio.mybluemix.net/docs/20.0.0.11/authentication.html

[dmuelle]

issues addressed in new editing pass:

• After authentication, an application can either obtain a JSON Web Token (JWT) from the social media service or associated OpenID Connect provider, or create a new one.->
  After authentication, an application can either create JSON Web Token (JWT) or obtain one from the social media service or associated OpenID Connect provider. DQTI Ch 6 AVOID AMBIGUITY
• This JWT can then authenticate the user to any service in the application. ->
  This JWT can then authenticate the user to other services that the application communicates with. CH4 accuracy

[chirp1]

Hi David,

Nice job with the topic! I have a few comments:

• Crisp up the words that go with the diagram so that they match better. For instance, the diagram says browser/client, but the description says user. You might also in the description mention the numbered steps that are in the diagram.
• Having "5. Create JWT" inside the Application rectangle seems inconsistent with the other rectangles and the oval in the diagram.
• I see an naming inconsistency in what you call the registries. Consistently call a particular registry by the same name.
• The sentence, "The Application Security feature provides core support for user registries in Open Liberty.", to me it says that it offers support for basic, custom, and LDAP user registries, since that is what the "User registries" section talks about. However, the Applicaiton Security feature lists only the basicRegistry configuration element. I don't see anything for LDAP or custom. If there is a discrepency, resolve it.
• Instead of having the six subsections under the "Single-sign on" section, how about if you have a bulleted list? Each bullet would be one of the titles for one of the six subsections. For example, "Social Media Login" would be the first bullet. Then, have this bullet link to the "Social Media Login" section in the SSO topic. Then, link the other five bullets to their section in the SSO topic. One issue is that your topic has an OpenID connect section that the SSO topic does not. Resolve the discrepency with the owner of the SSO topic. If there is info in your six subsections that aren't in the SSO topic, but should be, have the SSO topic writer add the information to the SSO topic.... The bulleted list is a suggestion. Feel free to come up with an alternative solution.
• At this point, I'll wait to see what you do with the six SSO subsections instead of editing the doc in them now.

[dmuelle]

@chirp1 thanks for reviewing. I made the following changes per your review:

https://draft-openlibertyio.mybluemix.net/docs/20.0.0.11/authentication.html

• Crisp up the words that go with the diagram so that they match better. I updated both the diagram and the description. I didn't end up adding the numbered steps to the description because it would have made the description much longer and more complex. If more detail is needed, I can revise the description into an ordered list to match the steps.

• Having "5. Create JWT" inside the Application rectangle seems inconsistent with the other rectangles and the oval in the diagram. moved this text outside of the square

• Consistently call a particular registry by the same name updated all references to be either "user registry", "basic user registry", "LDAP user registry", or "custom user registry".

• The sentence, "The Application Security feature provides core support for user registries in Open Liberty.", to me it says that it offers support for basic, custom, and LDAP user registries, since that is what the "User registries" section talks about. However, the Applicaiton Security feature lists only the basicRegistry configuration element. I don't see anything for LDAP or custom. If there is a discrepency, resolve it. removed this sentence as it was not consistent and didn't add much value anyway

• Instead of having the six subsections under the "Single-sign on" section, how about if you have a bulleted list? converted sections to a bulleted list of items that link to the relevant sections of the SSO doc. After discussing OIDC with @lauracowen, opted to remove it from the example and topic- strategically, it's mainly relevant as the underlying protocol for social logins and including a specific section about it doesn't add value for most users .

[dmuelle]

comments from @utle in 2746:

https://draft-openlibertyio.mybluemix.net/docs/20.0.0.11/authentication.html

• Should we link to the UserRegistry interface?
  If your application needs to reference a user registry other than a basic or LDAP user registry, you can configure a custom user registry by implementing the UserRegistry interface

• Should we have to same SSO order with https://draft-openlibertyio.mybluemix.net/docs/20.0.0.11/single-sign-on.html? Also the SSO provider link seem to link to the article not specific to the SSO provider.
  Open Liberty supports the following options for SSO authentication:

Social Media Login
JSON Web Tokens (JWT)
Lightweight Third Party Authentication (LTPA)
Security Assertion Markup Language (SAML)
Simple and Protected GSS-API Negotiation Mechanism (SPNEGO)

The SSO article have:

Social Media Login
JSON Web Tokens (JWT)
Simple and Protected GSS-API Negotiation Mechanism (SPNEGO)
Security Assertion Markup Language (SAML)
Lightweight Third Party Authentication (LTPA)

[dmuelle]

@utle thanks for reviewing:

• Should we link to the UserRegistry interface? There's currently no API documentation in Open Liberty, so for the time being, I've linked to the Liberty KC for this interface. However, this section and this link will be updated once Developing a custom user registry with BELLS #2418 "Developing a custom user registry with BELLS" publishes.

• Should we have to same SSO order with https://draft-openlibertyio.mybluemix.net/docs/20.0.0.11/single-sign-on.html?
  I've reordered the list to match the order in the SSO topic

• Also the SSO provider link seem to link to the article not specific to the SSO provider.
  This is a bug with the Open Liberty site that is being addressed in Loading a doc section doesn't always scroll to the right place in the content openliberty.io#1886

[chirp1]

Hi David,
Here are my latest comments:

• How about if you put the explanation of "custom user registry" before a discussion about it? So, for the User registries section, the"If your application needs to reference a..." paragraph explains the custom user registry. Put this paragraph before the "Open Liberty supports multiple user registries ", which mentions custom user registries.
• In the diagram, with the change to a more generic "SSO provider", now "5. Create JWT" seems too specific since you mention that the application can get a token or generate one: "After authentication, an application can either create JSON Web Token (JWT) or obtain one ".
• Add a reference to the JWT in your "In this diagram" paragraph.
• Possibly, Authorization could be removed from the diagram since you have another topic on authorization. However, the diagram in authentication and the diagram in authorization would need to fit together well. I
• In the diagram, don't put step 2 and step 5 on the same line. Investigate how to put together a flow chart. including in the IBM quality book for documentation: https://learning.oreilly.com/library/view/Developing+Quality+Technical+Information:+A+Handbook+for+Writers+and+Editors,+Third+Edition/9780133119046/ch11.html#ch11lev2sec2 and elsewhere.
• In the diagram, is "return" the correct word on step 7? I feel as though something is being returned to the user that they first gave out. "Receive" or some other word might work.
• For "In this diagram", mention what is happening with the token.
• You have a link that says "configure modules and contexts to customize authentication details. ". Does the topic linked to cover enough info for "contexts"? I see context mentioned in just one row of a table.

[dmuelle]

@chirp1 thanks for reviewing. I made the following changes to the draft:

• How about if you put the explanation of "custom user registry" before a discussion about it? updated
• In the diagram, with the change to a more generic "SSO provider", now "5. Create JWT" seems too specific since you mention that the application can get a token or generate one: "After authentication, an application can either create JSON Web Token (JWT) or obtain one ". added more context to example and description, changed term to "construct" JWT to match our JWT feature doc
• Add a reference to the JWT in your "In this diagram" paragraph. updated
• Possibly, Authorization could be removed from the diagram since you have another topic on authorization. waiting to see what happens with authorization diagram
• In the diagram, don't put step 2 and step 5 on the same line. reorganized diagram so step 5. in beneath the application, where JWT is constructed
• In the diagram, is "return" the correct word on step 7? changed to "send resources"
• For "In this diagram", mention what is happening with the token. updated
• You have a link that says "configure modules and contexts to customize authentication details. ". Does the topic linked to cover enough info for "contexts"? I see context mentioned in just one row of a table. split this into two links, one for module config element and oner for context entry config

[chirp1]

Hi!

• For the "...Social Media Login feature..." link, have the link include "feature" since you have a link further down to "Social Media Login" in the SSO topic, and the two links link to different information.
• You have " SSO identity provider" in a paragraph and "SSO provider" in the diagram. Use the same term in both.
• For "In the following diagram, a user ....", I'm finding the written description for the diagram and the diagram confusing. How about if you at least initially write the steps out like figures 2 and 3 at this link: https://www-03preprod.ibm.com/support/knowledgecenter/SSAW57_9.0.5_temp/com.ibm.websphere.nd.multiplatform.doc/ae/csec_SPNEGO_explain.html. Include more info in the written steps and about authentication than what is in the diagram. I think with the authorization info in it, some of the info is misleading. For instance, you say "This JWT contains information about the user’s identity and security roles that is used to authorize access to protected resources.". Although true, I think it misses emphasizing the JWT role in authentication. Wouldn't the JWT info be sent to "streaming music service might want to listen to a song, learn about the artist, and get recommendations for similar artists." that you mention earlier so that the user can be authenticated to the different services?

[dmuelle]

@chirp1 - made the following changes per your review:

• For the "...Social Media Login feature..." link, have the link include "feature" since you have a link further down to "Social Media Login" in the SSO topic, and the two links link to different information.

• You have " SSO identity provider" in a paragraph and "SSO provider" in the diagram. Use the same term in both.

• Revised the diagram description and reformatted it into an ordered list . Note- once the diagram and description are finalized and approved in this topic I will make corresponding edits to the Authorization topic, which has the same diagram.

https://draft-openlibertyio.mybluemix.net/docs/20.0.0.11/authentication.html

[chirp1]

@dmuelle Hi David, I spotted another item to comment on:

• For "The application communicates with other services, such as databases ", do you mean resources instead of services? I don't think a database on its own is a service, although I believe one can have a "database as a service, DBaaS".

[dmuelle]

@chirp1 I think although a database could be a web service, in most cases the application communicates with an API, which would in turn communicate with the DB. I've updated the sentence to be more clear:

The application communicates with other services, such as APIs, to complete the user’s request. These services use the JWT to authenticate the user’s identity and authorize access to resources that are permitted for the user’s security role.

[dmuelle]

published at https://www.openliberty.io/docs//latest/authentication.html

draft link: https://draft-openlibertyio.mybluemix.net/docs/latest/authentication.html

[brutif]

It's a tough topic to explain well, and all of you collaborated and did a good job on it. Hooray!!

[lauracowen]

Thanks @brutif - it's nice to get nice feedback :)