Introduction

Oauth 2.0 is an open standard protocol for authorization that enables an application to access certain user information or resources from another web service, without giving the user’s credentials for the web service to the web application.

Oauth 2.0 protocol uses number of actors and grant types to access to resources in another web application.

Actors:

• User or Resource Owner

• User Agent

• Client

• Authorization Server

• Resource Server (RS)

• Authorization Code - It is intermediate code exchanged via user agent(browser) for Oauth2 access token

• Implicit - OAuth2 access token is obtained within useragent (browser) e.g,., javascript clients

• Resource Owner Credentials – Username/password used for OAuth2 access token

• Client Credentials – Client credentials (clientid/secret) for OAuth2 access token e.g., modify client registration.

The following actions are performed by OAuth2 developer to access the resource on behalf of user without user credentials.

1. Get Oauth2 access token

• Present Oauth2 token to resource for access

• Refresh Oauth2 access token upon expiry

Refresh token is sent along with access token with supported grant types, those are, authorization code and resource owner credentials grant flow. This refresh token is used to get new access token upon expiry of access token with in valid authentication session.

Refresh token can’t be used for getting access token with additional scopes (access levels or attributes).

Refresh token can be used for an access token same equal or lesser value of scope then the original access token request.

Access token can be used to access protected resource. While client access protected resource valid (not expired) access token should be passed as bearer token part of authorization header. This is a popular approach of accessing resource server that is protected resource.

In order to give access resource server/ rest service end will validate the access token with OAuth2 server who issued this access token and get the scope information what information can be disclosed or given access.

1. Rest API – secured with Oauth2 standard authorization mechanism without handling user authentication.

• Publish API – Provide the public API to access the resources, and want to control the way user authenticates and apply authorization control.

• Mobile Clients – This is popular choice of implementing Oauth2 to access resource server resource by delegating authentication to Oauth2 provider. E.g., Get access token from the face book to read user profile/attributes to know about the user.

• ID token will be in JSON Web Token (JWT) format

• In addition token can be signed in compliance with JSON Web signing (JWS). This is optinal.

• ID token will JWT is made with header, payload and signing information. All this information is base64 encoded string respective values and joined with period “.”

• To get ID Token as part of OAuth2 authorization flow one additional scope value has to be added that is constant scope value “openid”

• OpenID Connect contains the following as payload

{
	"sub": "d4c094dd899ab0408fb9d4c094dd899a",
	"iss": "https://www.idp.com:8443/nidp/oauth/nam",
	"iat": 1427731685,
	"aud": "MRgPg4zooRNVM0LWtMnXlnKpu_h-zUV_9uTiA6Nnqmgjk0PNjZrm-ag",
	"exp": 1427735285
}
sub: user uid
iss: issuer url
iat: time stamp when this token issued
aud: Audience for whom this token is issued, value is clientID
exp: expiry time when the token will expire

1. Download the war file part of download file in this cool solution.
   Download netiq-playground.zip

• Deploy the webapp(war file) in Apache Tomcat 7.x or above

• Enable SSL with Apache Tomcat. https://tomcat.apache.org/tomcat-7.0-doc/ssl-howto.html

1. Sign in to Admin Console

• Enable Oauth2 protocol and update IDP

• Select Oauth & OpenID Connect protocol tab

• Do follow access manager 4.1 documentation to do the following
  
  1. Modify default resource servers “IDP User Resource” – this will modify userinfo endpoint output
     
     1. Create/modify scopes and map ldap attributes with scope name
     
     
  
  
• Modify global settings enable all grant types and token types

• Update IDP

• Register new client “NetIQPlayGround”. To do this click Oauth & OpenIDConnect protocol tab and click on “Client Applications” and follow documentation.
  
  1. Enter client name “NetIQPlayGround”
  
  
• Client type: web based

• Redirect URIs: add https://localhost:8443/netiq-playground/oauth2client (change localhost to IPaddress or full dns in case playground url is accessed on different system other than tomcat deployed system.)

• Enabled all grants checkboxes

• Enable all token types checkboxes

• Click Register client

• Update IDP

• On successful registration of client Identity Provider (IDP) will give clientID and secret

• Note down the above Client ID and Secret

• Note down end point summary includes token endpoint, userinfo endpoint, authorization endpoint

1. Create test user in user store

• Compete user profile

1. Make sure apache tomcat where you deployed playground is up and running

• Access the URL http://localhost:8443/netiq-playground/

• Click on Start, shows first step of testing Oauth2 and OpenID Connect

• Select the grant type and fill the required information
   
  
   
  
  • Authorization Grant Type: Authorization Code, Implicit, Client Credentials, Resource Owner Credentials
  
  
• ClientID: step above client registration setup noted down this value

• Scope: It is a scope name created as part of Oauth2 configuration with NetIQ access manager. Include scope “openid” if you want to do OpenID Connect to get ID_token

• CallbackURL: used this url to redirect back the control after authentication with identity provider. This is the same value entered while registering the client in above steps

• Authorization Endpoint: NetIQ Access Manager authorization endpoint. E.g., https://www.idp.com:8443/nidp/oauth/nam/authz

• Client Secret: in case of client credentials do enter the secret issued by IDP while registering the client

• Resource Owner username: In case of Resource owner credentials grant do enter the test user name

• Resource Owner password: In case of Resource Owner Credentials grant do enter the test user password

• On submit user will be redirect to IDP for user authentication

• Enter credentials and submit

• On successful authentication, based the scope name, user will be prompted to give permission to share with client application that is playground

• Approve it

• User agent will be redirect to redirect url, comes back to playground

• In case of Authorization grant Authorization code is obtained and showed on screen.
   
  
   
  To get Access token, fill in Call back URL (Redirect URI), Client Secret and Access token end point which for e.g., https://www.idp.com:8443/nidp/oauth/nam/token
  

• For Additional information about HTTP request and response click on Request or Response drop content.

• Click on Get Access token button

• Client will contact IDP on Token endpoint and gets access code, refresh token, and ID_TOKEN ( if scope “openid” added before getting authorization code)
  

• Click on “Tokens” drop content to view tokens information.
   
  
   
  At Refresh token, RefreshToken link is provided to test the refresh token flow, which will get the new access token.
  

• Click on Request and Response drop content, This will show the HTTP Request and Response information

• To access User Endpoint Info, enter userendpoint url e.g., https://www.idp.com:8443/nidp/oauth/nam/userinfo

• Click on “Get User Info”

• IDP will return the user information defined with Oauth2 scope

• Click on Request and Response content drop links to see HTTP Request and Response information.

• Click on Home button to test other grants and follow the wizard and fill relevant input to complete the test.

1. This play ground can be accessed via mobile devices also, UI is responsive to mobile devices.

• To access playground from different system/device other than tomcat installed system, modify the urls host from “localhost” to system full dns string or IP Address. This change should reflect in redirect url used to registered with NetIQ Access Manager

1. If you see error "invalid_grant: Grant name is not valid as per the Oauth Specification", modify the mainRedirect.jsp at IDP /opt/novell/nam/idp/webapps/nidp/jsp
   Change the text from
   target = StringEscapeUtils.escapeHtml(target);
   To
   target = java.net.URLEncoder.encode(target);
   No need of IDp restart, test again.
   

• https://www.netiq.com/documentation/access-manager-41/admin/data/b1dj6b2f.html#b1dj6b2f

• http://oauth.net/2/

• http://tools.ietf.org/html/rfc6749

• http://oauth.net/2/http://tutorials.jenkov.com/oauth2/roles.html

• https://docs.wso2.com/display/IS500/OpenID Connect with the WSO2 Identity Server and WSO2 OAuth2 Playground