lauracowen commented 4 years ago

This new SSO intro topic is drafted based on sections from each of the following topics:

895 (Social Media Login)
901 (JWT)
928 (SPNEGO)
898 (SAML)
897 (LTPA)

Instead of providing non-Liberty-specific info about the topics, we can link elsewhere to that info. In the topics we provide, we can explain how to use that tech with Liberty. The JWT one has a slightly longer because it's a newer tech, it's what we'd like people to use, and MP JWT doesn't have that much doc out there already.

When this topic is completed, the individual SSO topics above should be deleted from draft (they're superceded by this shorter version).

I've left a bunch of comments in the file in bold that need completing. Then the whole thing just checking over that it makes coherent sense.

Where you're adding links to external info, see what you can find (for a start, provide multiple links if you think they're good and we can discuss which is best). I'm going to discuss with David and Charlotte what kind of guidance we should follow in terms of where is best to provide links to.

Rwalls1 commented 4 years ago

@lauracowen I've made some updates. For your comment about TLS in each section, are you implying that you think TLS configuration should be mentioned within SSO description? Also, are you questioning whether "transmission" is technically accurate? : https://draft-openlibertyio.mybluemix.net/docs/ref/general/#single-sign-on.html

lauracowen commented 4 years ago

@Rwalls1

"transmission" - yes, I'm not certain of the correct word.
TLS config in the SSO descriptions - I couldn't decide. If it is not relevant to all SSO method, I think it should just be mentioned in the relevant sections (and not at all at the top). However, if it's relevant to all of the SSO methods and ends up being that the same text goes in every section, it might be better to just have the little paragraph at the top and not mention it at all in the individual sections. I think you'll need to check with an SME exactly which ones it's relevant to. My guess would be that it's relevant to all and so the best place would be just the paragraph at the top and remove the TLS paragraph in each individual section.

lauracowen commented 4 years ago

@Rwalls1 "transmission" should be fine. Alasdair suggested this text for David's TLS topic: "It is also an important protocol for authenticated access to websites. Securing the transmission of authentication tokens such as JSON Web Tokens with TLS helps ensure that user credentials are not exposed as they are passed among different applications and services." That's basically the point I was trying to capture in your SSO topic.

Rwalls1 commented 4 years ago

@lauracowen Please review the latest update, I confirmed with Bruce Tiffany that TLS is relevant for all of the SSO methods, so I removed the reference in the individual sections: https://draft-openlibertyio.mybluemix.net/docs/ref/general/#single-sign-on.html

lauracowen commented 4 years ago

Thank you! A mix of really minor comments and some requests for slightly more info in places:

feel free to remove my comments that are in bold as you complete them.
I think this sentence reads badly "As the developer of the application, you are not responsible for securing and maintaining users' personal information. " - I think the developer is responsible but this sentence was probably trying to say that by using SSO they can delegate that responsibility to another service? (I don't know if that's a strictly accurate way to describe it but something like that?)
The para starting "You must also configure TLS..." - this reads as quite instructional and this isn't a task topic. Is it possible to start this para with a bit of the context? eg something about how most/all? of these SSO methods involve passing tokens back and forth between services (give a concrete example/scenario) and so it's important that the auth tokens aren't intercepted etc. You can enable TLS to encrypt...etc. (mainly switching the order of the sentence round but also providing a really brief example).
Is the syntax for the link to David's TLS topic different in some way? It opens the page in a new tab instead of in the same tab. Ah, does the link use the full URL or a relative one? Can you check what approach we should be using in the docs? I've a feeling that we should be linking to the .adoc file (and the website build constructs the relevant relative URLs) not the HTML output of the file (I'm guessing what your source uses here....). Ditto for all the links to other doc topics. A benefit of pointing to .adoc file is that, when we publish, the build will throw errors if we find we're linking to topics that haven't yet been published (eg the 'configuring spnego' topic is a little held up in need of tech info at the moment).
can you give "MicroProfile JSON Web Tokens (JWT) feature" in full on first mention. "MicroProfile JWT" seems to be fine after that though.
what source highlighting did you use in the end? is that using [source,javascript]? It's still not that "highlighted". :-/
Below the JSON file example, can you provide a really brief explanation of the key bits of info in there? Don't go full-on reference topic, but see if it's possible to just give an outline of what the file shows (see https://jwt.io/introduction/ for some background).
Think the "To configure..." sentence could be part of the previous paragraph (instead of a separate paragraph).
thanks for adding in the external links to more info. Could you chat with David about them? He was thinking about what guidance we should provide to the ID team as a whole about what sources are good/bad to use. We didn't conclude anything so this might help.
SAML - were you able to get sufficient info to answer my comments in bold? I wasn't sure how much detail was necessary (there seems to be more than in the SPNEGO description above, for instance) and it'd be nice if there were some example that helped the developer reading this know that, yes, SAML is the thing they need. In a similar way that the SPNEGO section says you'll need to use that if you have Active Directory in your org - is there something more concrete defining when you'd most likely be wanting to use SAML?

Rwalls1 commented 4 years ago

@lauracowen Please review, I think I've addressed most of your feedback, I will discuss the point about linking further with David as I noticed the syntax may need to be updated across several topics based on your suggestion: https://draft-openlibertyio.mybluemix.net/docs/ref/general/#single-sign-on.html

lauracowen commented 4 years ago

I've just signed this off but could you change the LTPA link to this wikipedia one instead? https://en.wikipedia.org/wiki/IBM_Lightweight_Third-Party_Authentication I know it's not so detailed but the reader can always google for more. The reason I think we should change is that LTPA is an IBM WAS technology so going to the wikipedia page is probably better than to a website I've never heard of.

peer review. @rw2513 The topic looks good! Just a few suggestions.

Introduction

“Single sign-on (SSO) enables users to sign in to applications by using one account instead of creating an account specifically for each application that they want to use. “ Is single sign on an authentication protocol? Maybe you should follow the SSO mention with “authentication”. Also, you can say “Single sign-on (SSO) enables users to sign in to applications by using one account instead of creating an account specifically for each different application.”
“For example, when a user signs in to a service that enables SSO,” Can you say “For example, when a user signs in an SSO enabled service” Similarly, “This token is then passed to any application that the user accesses” to “This token is then passed to any application accessed by the user”
“When SSO is enabled, the user’s authentication data is transferred between applications with secure tokens.” “transferred between applications”, Can you change, “between” to “among” as there can be more than two applications involved. Also, servers are involved, maybe you might want to include that, or just “services”.
“You can configure Transport Security Layer (TLS) to encrypt communications between services for any SSO method that you choose so that the authentication tokens are not intercepted during transmission.” Here, can you change “communications” to “communication”, as the term is in the context of the exchange of data and not the communication channels?

Social media login

“You can enable Social Media Login for any social media platform that uses the OAuth or OpenID Connect (OIDC) standard for authentication.” “for any social media platform”, does this mean any or from those available in the form?
In the second paragraph, ”The OpenID provider interacts with the user to authenticate them.” Should this be” The OpenID provider interacts with the user information/credentials to authenticate the user.” or similar?
“The application or its container then contacts the OpenID provider and obtains a JSON Web Token (JWT) that contains claims about the user, and completes authentication and authorization.”, should “completes authentication and authorization” be “completes authorization”, as authentication has already been completed according to the previous sentence.

JSON Web Tokens (JWT)

“Each consumer of the token can verify that they can trust the claims in it, by verifying that they trust the issuer’s signature of the token.” Can you change this to, “Each consumer of the token can verify the claims in the token, by confirming that they trust the issuer’s signature of the token.”
“After the consumer verifies the signature, they know that the content of the token hasn’t been altered since it was created.” Change, “hasn’t been altered” to “wasn’t altered”, Acrolinx flagged.
Acrolinx is also flagging some trademarks like Microsoft, Windows etc.
“A claim is a piece of information that is asserted about a subject that is represented as a name-value pair, which consists of a claim name and a claim value.” Can you change this to, “A claim is a piece of information that is asserted about a subject that is represented as a name-value pair, which consists of a claim name and a claim value.”, for conciseness.

LTPA

“LTPA provides a method of SSO configuration support to authenticate users when they are accessing applications.” Can you change this to, “LTPA is a method of SSO configuration to authenticate users for accessing applications.” For clarity and conciseness.
“ To complete authentication, a token is generated that contains details about the user identity.”, Can you modify to “a token is generated in a cookie form”, to provide context for the next sentence.

General

Links- the links for SPNEGO, SAML, and LTPA are external. I’m not sure if we should link externally.
Instead of “user’s identity” throughout the topic, can you say “user identity”. Though both are correct and used in IBM content, “user identity” sounds simpler.

Rwalls1 commented 4 years ago

@ManasiGandhi Thanks, I've incorporated your feedback where appropriate

Rwalls1 commented 4 years ago

New link: https://draft-openlibertyio.mybluemix.net/docs/20.0.0.9/single-sign-on.html

Rwalls1 commented 4 years ago

PR: https://github.com/OpenLiberty/docs/pull/1878/files

Rwalls1 commented 4 years ago

Editing References: https://learning.oreilly.com/library/view/developing-quality-technical/9780133119046/ch10.html https://learning.oreilly.com/library/view/developing-quality-technical/9780133119046/ch06.html

Rwalls1 commented 4 years ago

New topic link: https://draft-openlibertyio.mybluemix.net/docs/20.0.0.11/single-sign-on.html

dmuelle commented 4 years ago

comments from @utle in #2749

The TLS link does not work Secure communication with Transport Layer Security (TLS).
The SPNEGO configuration link does not work. For more information, see Configuring SPNEGO authentication in Open Liberty.

chirp1 commented 4 years ago

@Rwalls1 Hi Richard, this topic has a link to the SPNEGO spec: https://www-01preview.ibm.com/support/knowledgecenter/SSAW57_9.0.5/com.ibm.websphere.nd.multiplatform.doc/ae/csec_SPNEGO_explain.html In your topic, use the SPNEGO spec link as the link to more SPNEGO information.

chirp1 commented 4 years ago

@Rwalls1 HI! I see that you have one editorial reference. Please go back and use another one to spruce the topic and list the editorial reference in this issue.

More editorial comments:

Change "The method that you choose to use..." to "The method that you use..." (to get rid of extra words)
For "uses the OAuth or OpenID Connect (OIDC) standard" should the "or" be an "and"? I think OpenID connect is an authentication layer? Does it require OAuth? If so, you might also explain that point in the sentence.

Rwalls1 commented 4 years ago

Comments from @wrodrig

The following hyperlinks are not working

Here is the link https://draft-openlibertyio.mybluemix.net/docs/20.0.0.11/single-sign-on.html Under SPNEGO the hyperlink Configuring SPNEGO authentication in Open Liberty. is not working.

Also under SAML You can configure Open Liberty to enable SAML single logout. SAML single logout is a near-simultaneous logout of a user from a specific authentication session and from all active service provider sessions that are associated with the authentication session. Single logout can be initiated by both the service provider and the identity provider. To configure SAML for your application, you can enable the samlWeb feature.

samlWeb is not working

Rwalls1 commented 4 years ago

Comments from @wrodrig:

Hi, Thank you for your review. It seems like some of the links two links that were reported are now working but now, the Transport Layer Security TLS hyperlink is broken:

You can configure Transport Security Layer (TLS) to encrypt communication between services for any SSO method that you choose so that the authentication tokens are not intercepted during transmission. For more information, see Secure communication with Transport Layer Security (TLS).

And the social login hyperlink is broken: To configure Social Media Login for your application, you can enable the socialLogin feature.

Thanks again for all the hard work with this documentation.

Regards,

Rwalls1 commented 4 years ago

@wrodrig Please review, the links should be fixed now: https://draft-openlibertyio.mybluemix.net/docs/20.0.0.11/single-sign-on.html

Rwalls1 commented 4 years ago

@chirp1 Thanks, I have addressed your comments. The phrase "uses the OAuth or OpenID Connect (OIDC) standard" is correct because you can use either individually for authentication. I added an additional sentence to explain the relationship between the two.

chirp1 commented 4 years ago

@Rwalls1 Hi Richard,

Here are my comments:

For "Social Media Login is a form of SSO that enables ..." the link is to a commercial site. Instead, link to standards/specifications, for OAuth and OpenID Connect, which are mentioned later in the same paragraph..
For "JSON Web Token (JWT) is a standard that" , change the link to the JWT spec instead of a website.
For "shared between applications. ", is it more than two applications? Should "between" be "among"? Same questions for " "by SSO between different microservice applications."
I see that you used "between" 9 times in the topic. Would you go through all 9 occurrences and make sure that you are using "between" and "among" correctly? I think at least one or two of them should be "among".
Update the link for "Guide: Securing microservices with JSON Web Tokens. " as the link goes to a draft server and gets a 404.
Avoid need to, needs to, needing to across your topics as the phrases add in unnecessary words. So, rewrite "of needing to use a:" so that you don't use "needing".
Use active voice more. For instance, rewrite "SPNEGO can be used to provide SSO ..." and "SPNEGO can also be configured".
For "SAML is a standard that offers... " replace the SAML link since it is to some commercial company. Replace it with a link to the specification.
Spell out SPNEGO, SAML, and LTPA on first occurrence.
The link for LTP in "LTPA provides a method of SSO " is a link to a commercial company. Don't use a commercial company. Also, I think LTPA is an IBM technology, including for tWAS and Liberty, isn't it?
For "when the Application Security feature is enabled ", how about if you link to the Application Security feature?
Research "Active Directory server " and make changes as appropriate. I don't think "Active Directory" is a server. I think it is a service, maybe on a Windows server??

Rwalls1 commented 4 years ago

@chirp1 Thanks I've addressed most of your feedback, The link to the guide was working properly, the 404 error was due to the draft site being rebuilt while a build was running. I removed the Active Directory section and added a reference to Active Directory in the Social Media Login section based on feedback from Laura in a related issue. Also, I couldn't find an official spec for Social media login or LTPA, do you have an idea for what would be an acceptable authoritative source to include for either Social Login or LTPA: https://draft-openlibertyio.mybluemix.net/docs/20.0.0.11/single-sign-on.html

chirp1 commented 4 years ago

@Rwalls1 Hi Richard, Here are my comments:

For the "Social Media Login" link, let me explain further. Remove the link for those words. Instead link to link to standards/specifications, for OAuth and OpenID Connect, which are mentioned later in the same paragraph. So, for OAuth, you might link to https://tools.ietf.org/html/rfc6749. For OpenID Connect, here are some suggestions for specs. Maybe check with you developer as to what to point to.
I think a wording is missing after "to" in "You can also configure to work on Linux operating systems." Should it be "configure SPNEGO to work"?
For an LTPA link to a spec and so on, would you check with your developer?
For the names of the features mentioned in your topic, you now have a mix of the name on the title for the feature topic, and the element name for the feature. How about if you use the feature name on the topic title? For instance, use instead of mpJWT, use "MicroProfile JSON Web Token". Instead of "samlWeb" use "SAML Web Single Sign-On". Instead of " samlWeb f". Instead of "socialLogin", use "Social Media Login".

lauracowen commented 4 years ago

Links and specs Please don't link to specs for basic explanations of a concept like Social Media Login or JWT. Instead, link to websites that provide useful, understandable explanations of the concepts/technologies. Specs are primarily written for runtime developers to implement the runtime; they're not written for users/developers using the runtimes to develop applications. If they're interested in reading them they can find them on the internet. The links we're providing should be helping the user understand the basic concept, not the full spec. We shouldn't imply that they might need to go off to read the spec before they can understand the rest of the section. They just need basic introductions at that stage. If you must, add a link to the spec at the end of the section (or in parentheses somewhere if necessary).

For example, the JWT.io site provides a really nice explanation of what JWTs are at https://jwt.io/introduction/ (rather even than https://jwt.io/), which is why we don't try to re-explain the concept of JWTs. Please link to that from the first mention of JWT.

I think this matters less for things like Active Directory because, in this context, they'll be connecting to Active Directory because they have to (that's what their company has set up), not because they have to make a choice to use it but, even so, Microsoft has a more user-friendly explanation here: https://docs.microsoft.com/en-us/windows-server/identity/ad-ds/get-started/virtual-dc/active-directory-domain-services-overview that we could probably use instead of just linking to the spec.

Feature names Regarding naming of features, David and Charlotte have some guidance on when to use the full name versus the configuration name of the feature.

Rwalls1 commented 4 years ago

Latest PR: https://github.com/OpenLiberty/docs/pull/2906/files

chirp1 commented 4 years ago

@Rwalls1 Hi Richard, Almost there!

Change "For more information about using JWTs" to "For more information about using MicroProfile JSON Web Tokens".
Change the link on "such as Active Directory," to what Laura recommended: https://docs.microsoft.com/en-us/windows-server/identity/ad-ds/get-started/virtual-dc/active-directory-domain-services-overview
Remove the link on "Lightweight Third-Party Authentication (LTPA)" based on your input from Ajay.

lauracowen commented 4 years ago

Thanks - @Rwalls1 can you add back in the JWT.io/introduction link for JWT too pls - I found it useful for understanding what JWTs are?

lauracowen commented 4 years ago

LTPA - there should be something on ibm.com about LTPA as we (tWAS) own the definition of that.

chirp1 commented 4 years ago

@Rwalls1 The updates look good, Richard! Moving to "Ready to publish".

Charlotte-Holt commented 3 years ago

This published with Karen's editorial updates added. Closing this issue.

OpenLiberty / docs

SSO intro topic #1676

895 (Social Media Login)

901 (JWT)

928 (SPNEGO)

898 (SAML)

897 (LTPA)

peer review. @rw2513 The topic looks good! Just a few suggestions.