How to setup Single Sign-On

Modified on Wed, 17 Jan at 10:18 AM

Newired currently two authentication methods for user login to the Portal and Editor.

Password authentication - Simple authentication via username and password.
Single Sign-On authentication - Based on OAuth2/OpenID Connect.

Both authentication methods are independent. It is possible to use only one or both at the same time.

Supported Standards and Protocols

Newired supports Single Sign-On based on OAuth2/OpenID Connect 1.0 standard.

How to enable SSO

All Single Sign-On (SSO) configuration is located in the file

Newired/tomcat/conf/newired.properties

Single Sign-On by OAuth2/OpenID Connect is disabled by default and requires manual configuration.

Login by Password

How Password Authentication works

newired.auth.password.enabled = true

The default status is set to true.
When set to false, it is impossible to log in via username password.
- Portal and Editor do not provide UI for password authentication.
- REST API does not accept requests to log in via password.

List of Users Allowed to Use Password

newired.auth.password.allowedUsers = admin, service

Default empty.
When the list is empty (or undefined) then all users are allowed to use a password to log in.
When the list is not empty then only users in this list are allowed to use a password to log in.
When password authentication is disabled via newired.auth.password.enabled = false, no user can use password authentication.

Login by OAuth2 / OpenID Connect

newired.auth.oauth2.provider.<id>.<property> = <value>

Each OAuth2/OpenID Connect Provider has to be configured by a set of properties. Different providers may require different properties.

Possible configuration properties.

Property	Description	Default Value	Required
label	Label visible in UI		Yes
iconUrl	Icon used in UI	<empty>	No
clientId	Identification of client application. How OAuth2 Provider identifies an application that wants to use OAuth2.		Yes
clientSecret		<empty>	No
scope		openid, profile, email	No
authorizationUri			Yes
tokenUri			Yes
userInfoUri		<empty>	No
jwkSetUri		<empty>	No
clientAuthenticationMethod		basic	No
userInfoAuthenticationMethod		query	No
authorizationGrantType		authorization_code	No
userNameAttribute		sub	No
User Attribute Mapping OpenID Connect / UserInfo attributes that will be mapped to Newired User Identities
userAttributeMapping.login	Name of the attribute used for matching with Newired local identity while auto-create new local identities	email	No
userAttributeMapping.email	Name of attribute mapped to Newired User Identity property email.	email	No
userAttributeMapping.name	Name of attribute mapped to Newired User Identity property First name.	name	No

Example:

newired.auth.oauth2.provider.google.label=Google
newired.auth.oauth2.provider.google.clientId=<clientId>
newired.auth.oauth2.provider.google.clientSecret=<clientSecret>
newired.auth.oauth2.provider.google.authorizationUri=https://accounts.google.com/o/oauth2/v2/auth
newired.auth.oauth2.provider.google.tokenUri=https://www.googleapis.com/oauth2/v4/token
newired.auth.oauth2.provider.google.userAttributeMapping.login=email

Which Users are Allowed to use SSO for Newired

Responsibility of decision which users can use SSO for Newired Portal and Editor in on the OAuth2/OpenID Connect provider. OAuth2/OpenID Connect Providers typically defines a group of users that are allowed to authenticate to a particular client application (e.g. Newired).

For example, Azure AD handles this situation with the following page.

Note
AD FS handles the described situation by redirecting back to the client application (Portal) with the following error.

Tested OAuth2 Providers

The implemented solution provides generic support for OAuth2/OpenID Connect, so it should generally work with any OAuth2 provider. There are examples of configurations for particular OAuth2 Providers.

Google

Property	Value
clientId	<id>
clientSecret	<secret>
authorizationUri	https://accounts.google.com/o/oauth2/v2/auth
tokenUri	https://www.googleapis.com/oauth2/v4/token
userInfoUri	https://www.googleapis.com/oauth2/v3/userinfo
jwkSetUri	https://www.googleapis.com/oauth2/v3/certs
scopes	openid,profile,email
userAttributeMapping.login	email
userAttributeMapping.email	email
userAttributeMapping.name	name

AD FS

Property	Value
clientId	<id>
clientSecret	<secret>
authorizationUri	https://<hostname>/adfs/oauth2/authorize/
tokenUri	https://<hostname>/adfs/oauth2/token/
jwkSetUri	https://<hostname>/adfs/discovery/keys
scopes	openid
userAttributeMapping.login	upn
userAttributeMapping.email	upn
userAttributeMapping.name	unique_name

Azure Active Directory

Property	Value
clientId	<id>
clientSecret	<secret>
authorizationUri	https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/authorize
tokenUri	https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token
jwkSetUri	https://login.microsoftonline.com/common/discovery/keys *[1]*
scopes	openid,profile,email
userAttributeMapping.login	preferred_username
userAttributeMapping.email	preferred_username
userAttributeMapping.name	name

GitHub

Property	Value
clientId	<id>
clientSecret	<secret>
authorizationUri	https://github.com/login/oauth/authorize
tokenUri	https://github.com/login/oauth/access_token
scopes	read:user
userNameAttribute	id
userAttributeMapping.login	email
userAttributeMapping.email	email
userAttributeMapping.name	name

How to get Configuration Values

To obtain configuration values for the following properties could be used OpenID Connect Discovery Document (aka OpenID Connect Metadata Document) provided by OAuth2/OpenID Connect Provider.

Where to find OpenID Connect Discovery Document

Google	https://accounts.google.com/.well-known/openid-configuration
AD FS	https://<hostname>/adfs/.well-known/openid-configuration
AAD	https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration

Interesting configuration properties

Property from Discovery Document	Newired configuration keys
token_endpoint	tokenUri
jwks_uri	jwkSetUri
authorization_endpoint	authorizationUri
userinfo_endpoint	userInfoUri

Redirect URL

To configure Newired as a client application in an OAuth2 provider is needed to set a redirect URL. Redirect URL should be composed as follows:

<newired-server-url>/login/oauth2/code/<providerId>

Example

https://example.com/login/oauth2/code/google

How to add parameters into Authorization Request

Additional parameters for the Authorization Request can be directly added into authorizationUri property.

newired.auth.oauth2.provider.<id>.authorizationUri=<uri>?param=value

Example:

newired.auth.oauth2.provider.google.authorizationUri = https://accounts.google.com/o/oauth2/v2/auth?prompt=consent

Note: Do not use slash "/" character between URI and parameter (Wrong: ../authorize/?param=value).

User Identity Auto-Create

When a User log-in into the Portal (or the Editor) via SSO for the first time then Newired creates a new identity automatically. Created identity has the same privileges as user identities created in the Portal manually.

Mapping OpenID Connect attributes to User Identities properties

OAuth2/OpenID Connect provides information like e-mail, name, etc. that can be mapped to properties in Newired User Identities. There are three mappings that can be used.

Configuration Property	Value example	Newired
newired.auth.oauth2.provider.<provider>.userAttributeMapping.login	preferred_username	user.ssoLogin
newired.auth.oauth2.provider.<provider>.userAttributeMapping.email	email	user.email
newired.auth.oauth2.provider.<provider>.userAttributeMapping.name	name	user.firstName

Example of Mapping for Azure AD

OpenID Connect Attributes

sub: X6mwOvKiwzCd5fha6kLddeZtGX3y2QBMRRBcvt-VH_0
ver: 2.0
roles: ["Admin"]
iss: https://login.microsoftonline.com/91b110fd-cabae5/v2.0
oid: 2eec07b5-b338-4f53-913e-30e1000ec791
preferred_username: [email protected]
uti: x2YrWc5PFEyHsckt64GfAA
nonce: v4VTNONWRvBh63NnY98wBTaBRG3JiJwMiZbAfy3EfjM
tid: 91b110fd-caba-43fb-854e-e31598becee5
aud: [fb7dc2a7-ef3f-4142-8f56-874dfbf262d2]
nbf: Wed Feb 23 08:57:00 CET 2022
rh: 0.AV0A_RCxkbrK-0OFTuMVmL7O5afCffs_70JBj1aHTfvyYtJdAMs.
name: Tester
exp: 2022-02-23T09:02:00Z
iat: 2022-02-23T07:57:00Z

Mapping

newired.auth.oauth2.provider.azure.userAttributeMapping.login=preferred_username
newired.auth.oauth2.provider.azure.userAttributeMapping.email=preferred_username
newired.auth.oauth2.provider.azure.userAttributeMapping.name=name

Created User entity

sso_login	[email protected]
login	[email protected]
password	NULL
email	[email protected]
first_name	NULL
last_name	Tester
origin	OAUTH2

Differences Between SSO Identity and Newired Local Identity

Newired / local identity.

User identity created manually requires login and password to authentication.

sso_login	NULL
login	johnny
password	secret
email	[email protected]
first_name	Johnny
last_name	Smith
origin	LOCAL

Note: This identity can not be used for SSO until it has filled sso_login (typically e-mail address). The Portal (version 22.1.0) does not allow set sso_login. Therefore locally created User Identity can be used for SSO only after manual update directly in the database.

SSO Identity

User identity auto-created after the first login via SSO.

sso_login	[email protected]
login	[email protected]
password	NULL
email	[email protected]
first_name	Smith
last_name	NULL
origin	OAUTH2

This identity can not be used for login via password until it has filled the password property. This can be done in the Portal.

There is a possible conflict between Newired Identity and SSO Identity in the value of "'login" property. If there is already a User entity with the same "login" that auto-create wants to use then it is used suffix _sso.

Example:

sso_login	[email protected]
login	[email protected]_sso
password	NULL
email	[email protected]
firstName	Smith
lastName	NULL
origin	OAUTH2

Logout and Selecting SSO Identities

Logout operation in the Portal terminates only a Newired user session. It does not log out SSO User Identity from a web browser window. This implies the following scenario.

When a user is already signed-in with SSO identity in a web browser then after clicking the button "Login with <Provider>" OAuth2 provider may automatically choose a signed-in identity and return back to the Portal without need or possibility to choose an identity.

After Portal logout and repeated "Login with <Provider>" OAuth2 provider again automatically chooses the same identity that is still signed-in the browser.

OAuth2 Providers typically offer UI to choose identity when the user is signed-in with more identities (in more tabs).

To choose another identity that is already logged in is typically needed to log out from SSO identity on the provider's page.