Overview

With NDS Labs v 1.0, we manage rudimentary account information in etcd and support account creation through a simple form. Going forward, we need to support standard account signup and approval workflows, as well as password recovery and management features. We We've discuss discussed leveraging Oauth and using external IdPs (e.g., Github) .  Using Oauth raises the question of whether we need to run our own IdP for users without Github or other external accounts.

If we rely exclusively on external IdPs, we avoid needing to provide the standard registration/verification workflow as well as password recovery and management. We will still need to deal with authentication and authorization into our service. This likely means implementing an authorization and approval workflow after the user has "signed up" with the selected Oauth provider.

If we decide to host our own IdP, we'll need to select from available open source identity service providers (below) and we will still need to deal with authentication and authorization into our service.

Requirements

• Ability to manage users and groups
• Login, forgot password, password reset
• Signup and approval workflow
• Oauth support

Prototype

• Implement Oauth in API server or other Oauth sample SP
• Implement WSO2 IdP with custom login (InfoRecoverySample)
• Federated authenticator with Github?

Oauth 2.0 overview

https://www.digitalocean.com/community/tutorials/an-introduction-to-oauth-2

• Register service with Oauth identity provider
• Authorization flow 

Image Removed

The Oauth identity provider is the service you will rely on to store user credentials, in our case Github.com. When the user selects to "sign up" with Github.com, the authorization flow begins and the user is prompted to "authorize" our application to access their profile information.  In this case, the user is authorizing NDS Labs. In a later step, NDS Labs will need to authorized the user to access our resources.

Here, NDS Labs is a service provider and Github is an identity provider (in SAML terms). 

Running our own WSO2 IdP, NDS Labs becomes both service and identity provider and can serve as an Oauth IdP for other applications.

Candidate SSO Implementations

...

as a potential solution. This would allow us to hand off primary identity and password management.

After some discussion, we've decided to prioritize the following for the beta release

• Internal account and password management with registration and approval workflows
• Optional Oauth2 support, beginning with Github.

We have decided not to go forward with a full-featured internal IdP (e.g., WSO2). WSO2 seems the most value when we have many users, need to implement permissions, or need to support other auth protocols (e.g., Shibboleth)

Requirements

• User can sign-up (register) for an account
  • NDS-255:  Passwords should be hashed and never returned to client
  • NDS-213: Add email field to wizard
• NDS Labs support an approve/deny a registered user
  • NDS-212: Email verification and account approval email after registration
• User can sign-in using internal credentials:
  • NSD-255: Password should be hashed
• User can reset password
  • NDS-185: User should be able to change their Project login password
• User can recover a forgotten password
  • NDS-438: User can recover forgotten password
• User can sign-up/sign-in with Github
  • NDS-332: 

Oauth

Overview

https://developer.github.com/v3/oauth/#web-application-flow

Redirect users to request Github access (user approves NDS Labs to access profile):

https://github.com/login/oauth/authorize?client_id=GITHUB_CLIENT_ID&redirect_uri=CALLBACK_URL&scope=&state=RANDOM_STRING&allow_signup=bool

Github redirects back to us:

https://ndslabs.org/login/oauth/endpoint?code=AUTH_CODE&state=RANDOM_STRING

https://github.com/login/oauth/access_token?client_id=GITHUB_CLIENT_ID&client_secret=GITHUB_CLIENT_SECRET&code=AUTH_CODE&redirect_url=&state=RANDOM_STRING

Use Cases

User can sign-in with Github

NDS-330

• User selects "Sign-in" with Github
• User is redirected to  https://github.com/login/oauth/authorize
  • User approves access to NDS Labs
  • User is redirected to callback (e.g., ndslabs.org/oauth/github)
• If no account record exists
  • Account is created for user in unapproved state
  • User is redirected to 403/Forbidden page
  • NDS Labs support is notified of new account approval
• If account record exists and is not approved
  • User is redirected to 403/Forbidden page
• If account record exists and is approved
  • User is redirected to Dashboard

NDS Labs staff can approve/deny account

• NDS Labs staff receives email requesting access approval
  • Email contains links to approve/deny endpoints
• Select approve
  • Account is marked approved
  • Email sent to user notifying of approval
• Select deny
  • Account is marked unapproved
  • Email is sent to user notifying of deny?

CLI

• Login with Github (basic auth)
• Approve account
• Deny account

GUI/API server changes

Oauth support

• Add endpoints to handle oauth requests
  • GET /oauth/providers
    • Returns list of supported providers and info
  • POST /oauth/login
    • provider=github
    • code=AUTH_CODE
    • state=RANDOM_STRING

Registration

• POST /register
  • Send email to configured address abot
  • E-mail address must be unique

Account approval

• Add approval endpoint, only available to admin or with token
  • GET /requests/
  • PUT /requests/user/
    • Approve/Deny
    • Send email to user
    • Template

Account record

• Implement password hashing (bcrypy + salt)
• Add account status (approved unapproved)
• Add change password endpoint (authenticated user)
  • /accounts/user/password
  • POST body:
    • {  "currentPassword": "123456", "newPassword": "this.is.actually.a.much.much.better.password"  }
• Forgot password
  • /accounts/password
  • POST body:
    • {  "email": "email@email.com"  }
      • send a reset password e-mail to the account matching this e-mail address
    • {  "user": "namespace"  }
      • send a reset password e-mail to the account matching this username / namespace
  • Send email to user with link with temporary password that must be changed on login

Candidate SSO Implementations

Central Authentication Service

• SSO only (no user management)
• No oauth support

Gluu

...

...

WSO2

WSO2 seems to be the most viable solution for hosting our own IdP. This assumes that we cannot simply rely on external solutions, such as Github. Features include:

• Ability to manage users and groups: supported
• Signup (requires customizationSign-up: supported, requires customization (look and feel)
• Login : supported, (requires customization (look and feel)Forgot/reset password: requires custom UI development (API
• availablePassword management (requires customization)
• Account approval : (requires custom workflow)
  
  • https://docs.wso2.com/display/IS510/Using+Workflows+with+User+Management
• Oauth: supported
• Dashboard – will need to customize user dashboard for IdP

Other options

Sign up with Github

Simply allow the user to sign up with their Oauth account.  This still requires an account approval workflow, but without the need to host our own IdP. 

Steps:

1. Sign-up with Github
2. User is prompted to authorize beta.ndslabs.org
3. Once authorized, an account is created but in an unapproved state.
4. An email is sent to ndslabs support for authorization
5. We authorize/deny the user

• Shibboleth, Oauth, OpenID, SAML protocols
• Plugin  Github oauth

WSO2 example

Start the WSO2 identity server. This is a custom Docker image for NDS Labs with the Github oauth plugin. The IP address will be included in URLs from the service:

docker run -p 9443:9443 -it ndslabs/wso2is:dev 192.168.99.100

Start the Playground example webapp:

docker run -p 8080:8080 ndslabs/wso2is-playground:dev

Open a browser to the admin interface: https://192.168.99.100:9443/carbon/, login as admin/admin

You'll need to register the Playground app as a Github Oauth Application:

• https://github.com/settings/applications/new
• Name: WSO2
• Home URL: https://192.168.99.100:9443/commonauth
• Callback URL: https://192.168.99.100:9443/commonauth

This will give you the client ID and secret for the next step

In admin console, select Identity Providers > Add

• Name: Github
• Federated Authenticators > Oauth2
  • Enable Oauth2/OpenIDConnect = true
  • Client ID: From above
  • Secret: From above
  • Auth Endpoint URL: https://github.com/login/oauth/authorize
  • Token endpoint URL: https://github.com/login/oauth/access_token
  • Callback URL: https://192.168.99.100:9443/commonauth
• Just-in-time provisioning
  • Always

In admin console, select service providers > Add

• Name: Playground
• Inbound authentication > Oauth > Configure
  • Version 2
  • URL: http://192.168.99.100:8080/playground2/oauth2client
  • Allowed Grants: Code, Implicit
• This will generate another client/secret (used below)
• Local and Outbound > 
  • Federated Authentication = github

Open browser to playground: 

• 192.168.99.100:8080/playground2/oauth2.jsp
• Client ID = from Playground
• Scope = openid
• Callback URL = http://192.168.99.100:8080/playground2/oauth2client
• Authorize endpoint = https://192.168.99.100:9443/oauth2/authorize
  • Redirected to Github – login
• Confirm account created

Notes

• It should be possible to map claims (Github profile data into WSO2 data)
• It is possible to combine local IdP and Github login

See also

https://docs.wso2.com/display/ISCONNECTORS/Configuring+Github+Authenticator

http://wso2.com/library/articles/2016/02/article-how-to-setup-a-wso2-api-manager-store-login-with-google/

https://docs.wso2.com/display/IS500/Identity+Provisioning+Concepts

https://docs.wso2.com/display/IS510/How+To%3A+Login+to+the+Identity+Server+using+Facebook+Credentials#HowTo:LogintotheIdentityServerusingFacebookCredentials-ConfiguringclaimmappingsforFacebook

...