PhenixID

Step by Step – Aweria Mobile – MFA with PhenixID Authentication Services

Summary

This document will guide you through the steps to enable multi-factor authentication for Aweria Mobile.

System Requirements

  • PhenixID Authentication Server 2.7 or higher
  • Keystore file (.p12) for token signing

Instruction

Overview

This document will guide you through the steps to enable multi-factor authentication for Aweria Mobile.

Aweria Mobile integrates with PhenixID Authentication Services using OpenID Connect Authorization Code flow. For more info about OpenID Connect Authorization flow with PhenixID Authentication Services, please read this.

The authentication method used for Aweria Mobile is PhenixID OneTouch (mobile soft certificate app).

PhenixID OneTouch activation is protected by SSL Client Certificate Authentication (trusting SITHS and EFOS CAs).

 

Description of the authentication flow

The authentication contains two parts:

1. PhenixID OneTouch Activation. Performed once a day.

2. Aweria Mobile authentication. This actually logs in the user into the Aweria Mobile app.

PhenixID OneTouch Activation

1. User opens OneTouch activation URL in browser on computer with card reader

2. User authenticates with SITHS or EFOS card

3. PhenixID OneTouch activation QR code is presented

4. User picks up tablet where Aweria Mobile and PhenixID One Touch apps are installed

5. User opens PhenixID One Touch

6. User scans QR code. Keypair and certificate generation process will start.

7. User select PIN code to protect PhenixID One Touch certificate

8. Done. The PhenixID OneTouch certificate will expire within 24 hours. Once expired, the end user has to perform same procedure again.
The PhenixID OneTouch certificate subject will contain the HSA-ID suffix.
(Example: HSA-ID: TST5565594230-11B0. OneTouch certificate subject: 11B0)

 

Aweria authentication

This diagram displays the Aweria Mobile authentication flow.

  1. User opens Aweria Mobile app on tablet and clicks Login. This will start the tablet system browser
  2. The system browser will point to the authorization endpoint (PhenixID Authentication Services)
  3. PhenixID Authentication Services will prompt the user for a userID
  4. The user will enter the userID (example: 11B0)
  5. PhenixID Authentication Services will create a PhenixID OneTouch assignment to be approved
  6. The system browser will open the app PhenixID OneTouch
  7. PhenixID OneTouch app will download and present assignment for user to approve
  8. Once approved, PhenixID OneTouch app will jump back to the system browser
  9. The authentication has now been verified by PAS
  10. The browser redirects to -> 11 with an authorization code
  11. Aweria mobile app receives authorization code
  12. Aweria backend receives the authorization code
  13. Aweria backend sends authorization code to PAS token endpoint
  14. An ID Token is returned by PAS. Aweria will verify the token and if ok, login the user.

Configure PhenixID Authentication Services

Configure OneTouch Activation

  1. Change OneTouch certificate expiration to 24 hours by following the steps in this solution document.
  2. Login to Configuration Manager
  3. Activate PhenixID OneTouch using Scenarios->System->One Touch
  4. Setup PhenixID OneTouch activation with SSL Client Certificate by following the steps in this solution document (use the configuration examples in the document).
  5. Download this css and add it to <phenixid_root>/mods/com.phenixidentity~phenix-prism-enroll-pki~<version>/web/css/
  6. Open <phenixid_root>/mods/com.phenixidentity~phenix-prism-enroll-pki~<version>/web/index.html in a text editor
  7. Add reference to aweria.css.
  8. Save index.html.

Configure Aweria authentication

  1. Login to Configuration Manager
  2. Go to Scenarios->Federation->Keystore and upload the p12 file.
  3. Once uploaded, copy the keystore ID value. This will be used in later step.
  4. Go to the Advanced tab
  5. Open Authentication-HTTP
  6. Add authenticator: 
    {

"alias": "otAweria",

"name": "OIDCUidOneTouch",

"configuration": {

"pipeID": "PipeOIDCAuthorizationAweria",

"servicename": "aweria",

"enableHoneypot": "false",

"allowedRP": [

"aweria"

],

"loginTemplate": "ot_login-aweria.template",

"redirectTemplate": "oidcredirect.template"

},

"id": "otAweria"

    }

  7. Click Stage Changes and Commit Changes
  8. Click OIDC RP
  9. Add this RP: 
    {
		"id": "aweria",
		"name": "Aweria OpenID Connect RP",
		"displayName": "Aweria Ambulance",
		"password": "<set_a_password_here>",
		"allowedRedirects": [
			"aweria://oidc"
		]
	}

    Change these values to suite your environment:
    – password (client_password for token endpoint verification. Select a password of your choice.)
    – allowedRedirects (Ask the Aweria administrator for proper value(s))

  10. Click Stage Changes and Commit Changes
  11. Click Pipes
  12. Add this pipe: 
    {

"id": "PipeOIDCAuthorizationAweria",

"valves": [

{

"name": "InputParameterExistValidatorValve",

"enabled": "true",

"config": {

"param_name": "username"

}

},

{

"name": "ItemCreateValve",

"config": {

"dest_id": "dummy"

}

},

{

"name": "SessionLoadValve",

"config": {

"id": "{{request.session_id}}",

"require_session": "true"

}

},

{

"name": "PropertyAddValve",

"config": {

"name": "redirect_uri",

"value": "{{request.redirect_uri}}"

}

},

{

"name": "PropertyAddDateTimeValve",

"config": {

"name": "time",

"format": "n"

}

},

{      
  "name": "UUIDCreateValve",
  "config": {
    "name": "tmpcode"
  }
},

{

"name": "PropertyStringBase64EncoderValve",

"config": {

"source": "tmpcode",

"dest": "code"

}

},

{

"name": "PropertyAddValve",

"config": {

"name": "state",

"value": "{{request.state}}"

}

},

{

"name": "SessionClearAllAliasValve",

"config": {}

},

{

"name": "SessionBindValve",

"config": {

"alias": "{{item.code}}"

}

},

{

"name": "PropertyKeepValve",

"config": {

"name": "redirect_uri,state,code"

}

}

]

}
  13. Click Stage Changes and Commit changes
  14. Click Modules
  15. Add this module (if the module already exist, just modify the configuration of it): 
    {
"module": "com.phenixidentity~phenix-api-authenticate",
"enabled": "true",
"config": {
"tenant": [
{
"id": "aweria",
"displayName": "Aweria RP",
"allowedOperation": [
"collectJWTa"
]
}
]
},
"id": "http-auth-api"
}
  16. Click Stage Changes
  17. Click NODE GROUPS
  18. Add module to module_refs 
    "module_refs": "http-auth-api,....."
  19. Click Stage Changes and Commit Changes
  20. Click Pipes
  21. Add this pipe: 
    {
		"id": "collectJWTa",
		"valves": [
			{
				"name": "SessionResolveValve",
				"config": {
					"alias": "{{request.code}}",
					"require_session": "true",
					"require_auth_session": "false"
				}
			},
			{
				"name": "SessionDumpToLog",
				"config": {}
			},
			{
				"name": "ItemCreateValve",
				"config": {
					"dest_id": "{{request.user_id}}"
				}
			},
			{
				"name": "GenerateJWTTokenVavle",
				"config": {
					"subjectattribute": "{{session.user_id}}",
					"keystore": "0a821f7e-b548-40f9-b2ae-d5a430c069e7",
					"expire_seconds": "3600"
				}
			},
			{
				"name": "PropertyAddValve",
				"config": {
					"name": "redirect_uri",
					"value": "{{request.redirect_uri}}"
				}
			},
			{
				"name": "SessionDeleteValve",
				"enabled": "false",
				"config": {}
			}
		]
	}
  22. Change the configuration parameter “keystore” value in pipe. Enter the ID for keystore saved in previous configuration step.
  23. Click Stage Changes and Commit Changes
  24. Connect to the PhenixID Authentication Services server (backend) root folder.
  25. Download template 1, 2 and 3 file to <phenixid_root>/mods/com.phenixidentity~auth-http~<version>/templates/
  26. Download image to <phenixid_root>/mods/com.phenixidentity~auth-http~<version>/web/res/images/

Collect OIDC metadata

These metadata properties must be collected:

  • client_id = aweria
  • client_password = <the password set for the OIDC RP with id = aweria)
  • Token signing verification certificate. Extract the public certificate (including chain) from the p12-file. DO NOT distribute the private key.
  • Token endpoint = https://<phenixid_authentication_services>/api/authentication/collectJWTa
  • Authorization endpoint = https://<phenixid_authentication_services>/oidc/authenticate/logout/?nextTarget=https%3A%2F%2F<phenixid_authentication_services>%2Foidc%2Fauthenticate%2FotAweria%3Fresponse_type%3Dcode%26client_id%3Daweria%26scope%3Dopenid%26redirect_uri%3D<redirect_uri>Change <phenixid_authentication_services> and <redirect_uri> values to suit your environment.

 

 

Configure Aweria

Distribute (in a safe channel) OIDC metadata collected in previous step to an Aweria Mobile administrator.

The Aweria Mobile administrator will configure Aweria Mobile based on the OIDC metadata.

If additional redirect_uri values will be used by Aweria Mobile, these values must be added to the aweria OIDC RP configuration in PhenixID Authentication Services.

Appendix

An example phenix-store.json for Aweria authentication can be found here.

 

DISCLAIMER
Information provided in this document is for your information only. PhenixID makes no explicit or implied claims to the validity of this information. Any trademarks referenced in this document are the property of their respective owners.

The origin of this information may be internal or external to PhenixID. PhenixID makes all reasonable efforts to verify this information.

PhenixID - support.phenixid.se