README

Service to extend gcgov/framework

Primary purpose

Implement a full Oauth service for authenticating to app. Provides functionality to authenticate users via third party Oauth providers or username/password database.

Impact to application

Router:
- Adds routes:
  - Adds route /.well-known/jwks.json - provides endpoint to enable front end validation of tokens generated by the app
  - Adds route /.well-known/openid-configuration - provides public oauth configuration endpoint
  - Adds route /auth/fileToken - create a short lived access token that can be used in the url for supported routes
  - Adds route /auth/out - kills refresh token for user and removes any session and cookie data
  - Adds route /auth/authorize - GET and POST for authenticating user and generating access and refresh tokens
  - Adds route /auth/hybridauth/{provider} - Return endpoint for third party Oauth providers
  - Adds route /auth/verifyMfaSecret - used to configure user by validating MFA code and saving MFA secret for user
  - Adds route /auth/verifyMfaCode - for validating an MFA code for a user with MFA already configured
- Adds authentication guard:
  - All routes in application with authentication=true must pass this guard. Checks the HTTP Authorization header, or url parameter fileAccessToken for routes with allowShort.

Installation:

Require using Composer https://packagist.org/packages/gcgov/framework-service-auth-oauth-server
Add namespace \gcgov\framework\services\authoauth to \app\app->registerFrameworkServiceNamespaces()

Configuration

Allowed Users

By default, users attempting to sign in who not already present in the user database collection will be prevented from signing in. To enable sign in for any user who passes the third party Oauth provider authentication, set config variable blockNewUsers=false. When blockNewUsers=false, any user successfully authenticated by the third party Oauth provider will be automatically added to the database user config

$oauthConfig = oauthConfig::getInstance();
$oauthConfig->setBlockNewUsers( false );

New User Default Roles

When blockNewUsers=false, new users will be automatically added to the user database collection. To set the default roles that a new user should be assigned at creation, provide the roles to the setBlockNewUsers method.

$oauthConfig = oauthConfig::getInstance();
$oauthConfig->setBlockNewUsers( false, [ 'Role1.Read', 'Role2.Read', 'Role2.Write' ] );

gcgov / framework-service-auth-oauth-server

Maintainers

Details