Single Sign on and Oauth2 support

Owned by Samuel Githengi
Last updated: Sept 02, 2020

OpenSRP uses Oauth2 to support single sign on.


There are currently 2 options of using Oauth2 protocol when using OpenSRP

1. Spring oauth2 implementation

In this mode OpenSRP acts as both the authorization and resource server.

1.1 Building OpenSRP manually using Maven.

To enable Oauth one must deploy OpenSRP with Oauth2 profile enabled

mvn clean package  -Dmaven.test.skip=true -P oauth2,postgres,jedis


This build OpenSRP with the oauth 2 libraries included and configured


On Development when OpenSRP is being build manually one must configure the oauth2 clients on opensrp.properties. An example is provided below

#ouath settings
oauth.default.client.id=opensrp-trusted-client
oauth.default.grant.types=password,authorization_code,refresh_token,implicit
oauth.default.secret=O@aTHS#cr3t
oauth.default.scope=read,write,trust
oauth.default.token.validity=3600
oauth.default.callback.url=https://yourapplication.com/registered/callback

1.2 Building OpenSRP Using playbooks

When using playbooks when below configuration is required on the inventories to enable oauth2 profile and define 2 clients default and androidclient.

#Make sure to activate the oauth2 profile
opensrp_maven_package_profiles:
	- postgres
	- jedis
	- oauth2


opensrp_oauth_profiles:
  default:
	client_id: "opensrp-trusted-client"
	secret: "O@aTHS#cr3t"
	grant_types:
		- password
		- authorization_code
		- refresh_token
		- implicit
	scope:
		- read
		- write
		- trust
	token_validity: 3600
	callback_url: ""
	roles:
	- ROLE_CLIENT
  androidclient:
	client_id: "android-apps-client"
	secret: "Dr01dS#cr3t"
	grant_types:
		- password
		- refresh_token
	scope:
		- read
		- write
		- trust
	token_validity: 3600
	callback_url: ""
	roles:
		- ROLE_CLIENT


2. Keycloak


When using keycloak, OpenSRP has only the resource server, keycloak acts as the authentication server. To configure Keycloak refer to this Setting up Keycloak 

When configuring OpenSRP to use keycloak via playbooks define the below variables on your inventories for the OpenSRP group vars

#keycloak configs
opensrp_keycloak_realm: "your-realm"
opensrp_keycloak_auth_server_url: "keycloak auth URL"
opensrp_keycloak_client: "keycloak openid client name"
opensrp_keycloak_client_secret: "keycloak openid client secret"

To configure keycloak manually download  keycloak OIDC JSON config and store in WEB_INF foider when building your server. Refer to Setting up Keycloak and  https://www.keycloak.org/docs/latest/server_admin/#_client_installation for further details