Skip to main content

SSO

Single Sign On

This package adds single sign on (SSO) to your Qore application.

Auth Providers​

This plugin currently supports the following Providers out of the box: Okta, Facebook, Twitter, LinkedIn, Google, GitHub, GitLab, and Bitbucket.

To add more authentication providers see Extending.

Installation​

You can install the package via composer:

composer require qore/sso

Laravel​

php artisan qore:publish sso --migrations --config --force

Make sure to migrate.

php artisan migrate

Traits ​

1. Model relationship Qore\SSO\Traits\CanHaveSSOProviders.php​

This package comes with the SSOProvider model.
The CanHaveSSOLogin trait can be used in the project's user model to define a relationship.

/**
 * Class User
 * @package App\Models\Central
 */
class User extends QoreUser
{
    use Qore\SSO\Traits\CanHaveSSOLogin;
    ...
}
2. Fields Qore\SSO\Traits\HasSSOProvidersFields.php​

The SSO package contains a basic field to display whether a user logs in using SSO and which providers the user uses.

    ...
    use \Qore\SSO\Traits\HasSSOProvidersFields;
    ...
    public function fields(): FieldCollection
    {
        $collection = new FieldCollection();
        ...
        $collection->push($this->ssoProviderFields())
        ...
        return $collection;
    }

    public function fieldLayout(bool $forDetail, ?Model $model = null): ?FieldLayout
    {
        if ($forDetail) {
            $fields = [
                'socialUser',
                'name'
                ...

Frontend​

Register the SSO callback page.​

 php artisan qore:publish sso --frontend --force

This page is used to redirect to after authenticating with the OAuth server. In your frontend/src/router/routes.js add the published vue file as a child to the guest middleware:

  ...middleware('guest', [
    // Auth
    {
        path: '/',
        component: () => import('layouts/AuthLayout.vue'),
        children: [
            { 
                path: 'login-social/:provider/callback', 
                component: () => import('vendor/sso/LoginSocial'), 
                name: 'login-social' 
            }

Change the default login page​

In short you'll need to create a login button in the frontend.

<q-btn
    label="Log in with Google"
    @click="socialLogin('google')"
/>

And a method that dispatches the social login redirect.

methods: {
    async socialLogin (provider) {
        this.$store.dispatch(
            'auth/socialLoginRedirect',
            { provider: provider }
        )
    },

You could use Login.vue as reference:

  • It adds buttons to the default login page, for example an Okta button
  • It redirects the user to the provider's login page. Using the following method: socialLogin
  • It shows the login button for a specific provider if a user is required to use SSO using sso.state : GitLab

Configuration​

Credentials​

You will need to add credentials for the providers you'd like to use.

For more configuration information: https://laravel.com/docs/socialite

config/Services.php
    ...
    'okta' => [
        'base_url' => env('OKTA_BASE_URL'),
        'client_id' => env('OKTA_CLIENT_ID'),
        'client_secret' => env('OKTA_CLIENT_SECRET'),
        'redirect' => env('OKTA_REDIRECT_URI'),
        'auth_server_id' => env('OKTA_AUTH_SERVER_ID')
    ],
    ...
.env

OKTA_BASE_URL="https.."
OKTA_CLIENT_ID="eb1bd40cf031b1f1f105"
OKTA_CLIENT_SECRET="1c6743d4e9f6b86bd58088b39b33aee1"
OKTA_AUTH_SERVER_ID="e105a3fc17464ec3"
OKTA_REDIRECT_URI="${APP_FRONT_URL}/login-social/okta/callback"

Config​

  1. enabled: Option decides whether sso is enabled.

  2. enabled_providers: This option controls which Socialite Providers are enabled.

  3. provider_scopes: This option can be used to provide scopes for each provider.

  4. provider_domain_whitelist: This option restricts login by domain name

    e.g. Only users with the '@qlic.nl' domain are authorized to log in using the 'github' provider.

  5. requires_social_auth: This option defines whether users with a certain domain should log in using sso.

  6. extension_listeners: Used to register event listeners for manually required socialite providers. See Extending.

  7. user:

    1. model: The user model of the application.
    2. should_create: Determines whether or not a new user should be created when logging in for the first time.
    3. creator: The DefaultUserCreator class will be used to create new users. Your own implementation can be provided here.
    4. before_login_handler: The DefaultBeforeLoginHandler will used before the logging in a user. Your own implementation can be provided here.
    5. default_tenant:
      1. app_managed: If set to true default tenant fields won't be shown in the settings page.
      2. providers: This option controls which Tenant users should be assigned to after signing in for the first time. 
        Key Options:
            <provider name> or '*'
        Value Options:
            The tenant's id or name
    6. default_roles:
      1. app_managed: If set to true default role fields won't be shown in the settings page.
      2. providers: This option controls which roles users should be assigned after signing in for the first time. 
        Key Options:
            <provider name> or '*'
        Value Options:
            The role's name

Public routes​

The folowing routes could be used to implement your own front-end implementation.

Get SSO Providers​

GET 'api/login/social/providers'​

Get active OAuth providers.

Response​

Information in the response is retrieved from the sso.php config.

{
    'enabled': true,                // config('sso.enabled')
    'providers': ['okta', 'google'] // config('sso.enabled_providers')
}

Retrieve SSO State​

This route determines if a user should use SSO to log in based on the domain requires_social_auth in the config file.

Post Request Data​

{
    'email': 'mail@domain.com'
}

Response Body​

When the domain doesn't require SSO.

#config/sso.php
...
'requires_social_auth' => []
...

Response { 'ssoState': 'none' }

When the domain does require SSO.

# config/sso.php
...
'requires_social_auth' => [ 'qlic.nl' => 'okta' ]
...

Response: { 'ssoState': 'okta' }

Extending​

Authorization providers outside the default set of providers can be added if needed.

Visit socialiteproviders.com to find a collection of supported providers.

Most providers will work, but some require a more tedious setup. In that case provider specific updates need to be done to the plugin's source code.

1. Composer require​

First you'll need to require the desired provider from composer.

For example:

composer require socialiteproviders/google

2. Credentials​

You'll need to add the credentials in your own config/services.php and/or .env files.

3. Events​

Register the event listener in the config/sso.php config file.

'extension_listeners' => [
        [
            'listener' => '\\SocialiteProviders\\Google\\GoogleExtendSocialite',
            'handler' => 'handle'
        ],
]

4. frontend​

You'll need to create a login button in the frontend.

<q-btn
    label="Log in with Google"
    @click="socialLogin('google')"
/>

And a method that dispatches the social login redirect.

methods: {
    async socialLogin (provider) {
        this.$store.dispatch(
            'auth/socialLoginRedirect',
            { provider: provider }
        )
    },

SSO info​

Optionally you can use the vuex auth store to retrieve information about SSO.

  • sso.enabled: Determine whether SSO can be used to login.
  • sso.providers: Determine which providers are enabled.
    This enables the possibility to add login buttons dynamically. e.g. a f-vor="provider in sso.providers"

To do this implement the following in the project's Login.vue.

  1. Dispatch the following action in the mounted () method 
    mounted () {
        this.$store.dispatch('auth/retrieveSocialLoginInformation')
    },
  2. Add sso to the computed object. 
    computed: {
        ...mapState('auth', {
            status: state => state.status,
            errors: state => state.errors,
            sso: state => state.sso
        })
    },
  3. Implement your business logic based on the sso.enabled and sso.providers computed variables.

An example can be found in frontend/src/vendor/sso/Login.vue after publishing the frontend compontents.

5. Enable!​

Enable the newly added provider to the enabled_providers array in config/sso.php

    'enabled_providers' => [
        'okta',
    ],

Release notes​

All notable changes will be documented here.

0.3.2​

Features​

  • Disable user creation
    Introduces the ability to disable user creation for users that try to log in using SSO for the first time.
    This can be disabled in the config under the key user.should_create

0.2.0​

Features​

Version 0.2.0 introduces a settings page for the plugin where a user can:

  • Enabled or disable SSO completely (global level)
  • Enable or disable providers (provider level)
  • Assign a default role or tenant for new users (global level)
  • Assign a default role or tenant for new users (provider level)
  • Provide domains that should be forced to use sso (provider level)
  • Provide email addresses that shouldn't be forced to sso. (global level)
  • Provide a domain whitelist (provider level)

Notable changes​

  • Changes have been made to the config file. The config file will now be used to initially seed SSO settings in the database.
  • This version includes new Models and Migrations.

Make sure to update/publish the config and migrations:

php artisan vendor:publish --tag=qore.login-branding.db --force
php artisan vendor:publish --tag=qore.login-branding.frontend --force

Don't forget to run migrations.

0.1.1​

Features​
  • Add the ability to provide scopes for each provider in the config.
  • Add the ability to provide a before login handler in the config.

Notable changes​

  • The config has been changed make sure to update/publish your config.

    php artisan vendor:publish --tag=qore.sso.config --force