diff --git a/source/scim/azure.rst b/source/scim/azure.rst deleted file mode 100644 index 1b1a9b400..000000000 --- a/source/scim/azure.rst +++ /dev/null @@ -1,43 +0,0 @@ -:orphan: - -Azure portal -============ - -References: ------------ - -- `Use scim to provision users and groups `_ - -Setup ------ - -- Connect to your `Azure portal `_ and go to the **Azure Active Directory** > **Enterprise applications** menu. -- Select **New application** and choose **Create your own application**. -- Choose a name for your application, select **Integrate any other application you don’t find in the gallery (Non-gallery)** and click on the **[Create]** button. - -.. figure:: pics/azure-1.png - :alt: Azure create app - -- In the “Provisioning” section, - - - Select **Automatic**, - - Fill **Tenant Url** with the API url of your SCIM server you copied from the :ref:`plugin configuration `. - - Optionally, fill **Secret** field: - For Azure, the awaited secret is a long life valid jwt token. - We cannot use an oauth exchange (Azure doesn’t ask for an authorize URL). - So in GLPI, setup you SCIM server with **Bearer** security and paste the JWT token from GLPI in the **Secret token** field of Azure. - - Click on the **Test connection** button to validate your parameters. - - If the test succeed, click on the **[Save]** button. - - .. figure:: pics/azure-2.png - :alt: Azure Configuration provisioning - - - - You must choose in the **Parameters** > **Extended** section how you want to synchronize your users and groups: - - - Only users and groups assigned to the application. In this case, you must manually assign your users and groups to the application in the **Users and groups** section. - - All users and groups in the directory - - - After checking the mapping section, enable the **Provisioning** at the bottom and click on the **[Save]** button. - - You can check the advancement in the **Provisioning logs** section. - Usually it start after a few minutes. diff --git a/source/scim/entra.rst b/source/scim/entra.rst new file mode 100644 index 000000000..d6d6f8e3e --- /dev/null +++ b/source/scim/entra.rst @@ -0,0 +1,123 @@ +Entra +----- + +References: +~~~~~~~~~~ + +- `Use SCIM to provision users and groups `_ + +Setup +~~~~~ + +Create application +~~~~~~~~~~~~~~~~~~ + +- Connect to your `Azure portal `_ +- Click on **Add** +- then **Enterprise application**. + +.. figure:: images/scim-4.png + :alt: add application + :scale: 65 % + +- Click on **Create your application**. +- In the section that appears on the right, enter the name of your application and choose the 3rd option **`integrate any other application don't find in the gallery`**. + +.. figure:: images/scim-5.png + :alt: create application + :scale: 43 % + + +Setup the application +~~~~~~~~~~~~~~~~~~~~~ + +- Once you've created your application, go to **Provisioning**. + +.. figure:: images/scim-6.png + :alt: add provisionning + :scale: 100 % + +- Select **Automatic**. +- Specify the **URL** `generated earlier `_ from GLPI and paste the **token**. + +.. Warning:: Make sure you **paste the token (JWT token)** to ensure your application works properly. + +.. figure:: images/scim-7.png + :alt: setup provisionning + :scale: 75 % + +- Click on Test connection. A message will appear informing you of the successful connection. + +.. figure:: images/scim-8.png + :alt: setup provisionning + :scale: 100 % + +- On the same page, you can also configure an email address and a number in case of failure or accidental deletions. + +.. figure:: images/scim-9.png + :alt: check provisionning + :scale: 100 % + + +- Click on **Save** + + +Synchronising all users +~~~~~~~~~~~~~~~~~~~~~~~ + +- You can choose to synchronise your entire directory. +- Go to the **Settings > Scope** tab and select **Sync all users and groups**. + +.. figure:: images/scim-10.png + :alt: sync all + :scale: 67 % + +Synchronising selected groups and users (default option) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- You can choose to synchronise only certain groups and/or users. When refreshing the **`Provisionning`** page +- Go to the **Parameters > Scope** tab +- Select **Synchronise assigned users and groups only** + +.. figure:: images/scim-11.png + :alt: sync selection + :scale: 100 % + +- Then go to **Users and groups** +- Click on **Add a user/group** +- Click on **No selection** +- Select the groups and users you want in the box on the right +- Then **Select** and **Assign**. + +.. figure:: images/scim-12.png + :alt: select users/groupes + :scale: 43 % + +Activate provisioning +~~~~~~~~~~~~~~~~~~~~~ + +- In the **Provisioning** section +- Change the status from **Disabled** to **Enabled** + +.. figure:: images/scim-13.gif + :alt: enable sync + :scale: 100 % + + +Check synchronisation status +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- In the **Overview** section, you can check that synchronisation has been successful. + +.. figure:: images/scim-14.png + :alt: check provisionning + :scale: 82 % + +- On the GLPI side, Go to the **Request log** section of your SCIM plugin **Setup** > **SCIM identity servers** to check that the accounts are correctly synchronised. + +.. figure:: images/scim-15.png + :alt: check provisionning + :scale: 43 % + +.. Important:: + See the procedure for setting up the `OAuth SSO `_ plugin to authenticate users on GLPI. \ No newline at end of file diff --git a/source/scim/faq.rst b/source/scim/faq.rst new file mode 100644 index 000000000..0ba33b039 --- /dev/null +++ b/source/scim/faq.rst @@ -0,0 +1,4 @@ +FAQ +--- + +If you have any questions about using the plugin, please consult `our FAQ `_ \ No newline at end of file diff --git a/source/scim/pics/azure-1.png b/source/scim/images/azure-1.png similarity index 100% rename from source/scim/pics/azure-1.png rename to source/scim/images/azure-1.png diff --git a/source/scim/pics/azure-2.png b/source/scim/images/azure-2.png similarity index 100% rename from source/scim/pics/azure-2.png rename to source/scim/images/azure-2.png diff --git a/source/scim/pics/identity_server.png b/source/scim/images/identity_server.png similarity index 100% rename from source/scim/pics/identity_server.png rename to source/scim/images/identity_server.png diff --git a/source/scim/pics/logo.png b/source/scim/images/logo.png similarity index 100% rename from source/scim/pics/logo.png rename to source/scim/images/logo.png diff --git a/source/scim/pics/okta-1.png b/source/scim/images/okta-1.png similarity index 100% rename from source/scim/pics/okta-1.png rename to source/scim/images/okta-1.png diff --git a/source/scim/pics/okta-2.png b/source/scim/images/okta-2.png similarity index 100% rename from source/scim/pics/okta-2.png rename to source/scim/images/okta-2.png diff --git a/source/scim/pics/okta-3.png b/source/scim/images/okta-3.png similarity index 100% rename from source/scim/pics/okta-3.png rename to source/scim/images/okta-3.png diff --git a/source/scim/images/scim-1.png b/source/scim/images/scim-1.png new file mode 100644 index 000000000..d25bea4be Binary files /dev/null and b/source/scim/images/scim-1.png differ diff --git a/source/scim/images/scim-10.png b/source/scim/images/scim-10.png new file mode 100644 index 000000000..80e191c5a Binary files /dev/null and b/source/scim/images/scim-10.png differ diff --git a/source/scim/images/scim-11.png b/source/scim/images/scim-11.png new file mode 100644 index 000000000..02fc30de8 Binary files /dev/null and b/source/scim/images/scim-11.png differ diff --git a/source/scim/images/scim-12.png b/source/scim/images/scim-12.png new file mode 100644 index 000000000..254557c80 Binary files /dev/null and b/source/scim/images/scim-12.png differ diff --git a/source/scim/images/scim-13.gif b/source/scim/images/scim-13.gif new file mode 100644 index 000000000..88f9bf217 Binary files /dev/null and b/source/scim/images/scim-13.gif differ diff --git a/source/scim/images/scim-14.png b/source/scim/images/scim-14.png new file mode 100644 index 000000000..b0db54061 Binary files /dev/null and b/source/scim/images/scim-14.png differ diff --git a/source/scim/images/scim-15.png b/source/scim/images/scim-15.png new file mode 100644 index 000000000..d66f80a80 Binary files /dev/null and b/source/scim/images/scim-15.png differ diff --git a/source/scim/images/scim-16.png b/source/scim/images/scim-16.png new file mode 100644 index 000000000..54408e359 Binary files /dev/null and b/source/scim/images/scim-16.png differ diff --git a/source/scim/images/scim-17.png b/source/scim/images/scim-17.png new file mode 100644 index 000000000..4d50e0374 Binary files /dev/null and b/source/scim/images/scim-17.png differ diff --git a/source/scim/images/scim-18.png b/source/scim/images/scim-18.png new file mode 100644 index 000000000..cc2dcd659 Binary files /dev/null and b/source/scim/images/scim-18.png differ diff --git a/source/scim/images/scim-19.png b/source/scim/images/scim-19.png new file mode 100644 index 000000000..aa5eb01fc Binary files /dev/null and b/source/scim/images/scim-19.png differ diff --git a/source/scim/images/scim-2.png b/source/scim/images/scim-2.png new file mode 100644 index 000000000..698bf18c6 Binary files /dev/null and b/source/scim/images/scim-2.png differ diff --git a/source/scim/images/scim-20.png b/source/scim/images/scim-20.png new file mode 100644 index 000000000..a33f6a22b Binary files /dev/null and b/source/scim/images/scim-20.png differ diff --git a/source/scim/images/scim-21.png b/source/scim/images/scim-21.png new file mode 100644 index 000000000..0d7830ec4 Binary files /dev/null and b/source/scim/images/scim-21.png differ diff --git a/source/scim/images/scim-22.png b/source/scim/images/scim-22.png new file mode 100644 index 000000000..fb0376eaf Binary files /dev/null and b/source/scim/images/scim-22.png differ diff --git a/source/scim/images/scim-23.png b/source/scim/images/scim-23.png new file mode 100644 index 000000000..63dcd54ba Binary files /dev/null and b/source/scim/images/scim-23.png differ diff --git a/source/scim/images/scim-24.png b/source/scim/images/scim-24.png new file mode 100644 index 000000000..57a091c02 Binary files /dev/null and b/source/scim/images/scim-24.png differ diff --git a/source/scim/images/scim-3.png b/source/scim/images/scim-3.png new file mode 100644 index 000000000..b189422ca Binary files /dev/null and b/source/scim/images/scim-3.png differ diff --git a/source/scim/images/scim-4.png b/source/scim/images/scim-4.png new file mode 100644 index 000000000..813873e44 Binary files /dev/null and b/source/scim/images/scim-4.png differ diff --git a/source/scim/images/scim-5.png b/source/scim/images/scim-5.png new file mode 100644 index 000000000..1757cb431 Binary files /dev/null and b/source/scim/images/scim-5.png differ diff --git a/source/scim/images/scim-6.png b/source/scim/images/scim-6.png new file mode 100644 index 000000000..c8129d600 Binary files /dev/null and b/source/scim/images/scim-6.png differ diff --git a/source/scim/images/scim-7.png b/source/scim/images/scim-7.png new file mode 100644 index 000000000..b474be27e Binary files /dev/null and b/source/scim/images/scim-7.png differ diff --git a/source/scim/images/scim-8.png b/source/scim/images/scim-8.png new file mode 100644 index 000000000..b18e591ad Binary files /dev/null and b/source/scim/images/scim-8.png differ diff --git a/source/scim/images/scim-9.png b/source/scim/images/scim-9.png new file mode 100644 index 000000000..1258d9de5 Binary files /dev/null and b/source/scim/images/scim-9.png differ diff --git a/source/scim/images/scim_api.png b/source/scim/images/scim_api.png new file mode 100644 index 000000000..9972c4e33 Binary files /dev/null and b/source/scim/images/scim_api.png differ diff --git a/source/scim/index.rst b/source/scim/index.rst index 8a3632a01..5a6963d5e 100644 --- a/source/scim/index.rst +++ b/source/scim/index.rst @@ -1,87 +1,13 @@ SCIM ==== -Requirements (on-premise) -------------------------- - -============ =========== =========== -GLPI Version Minimum PHP Recommended -============ =========== =========== -10.0.x 8.1 8.2 -============ =========== =========== - -.. note:: - A `basic licence `_ (or higher) is required. This plugin is also available from the `Cloud `_. - - -.. figure:: pics/logo.png - :align: Center - :scale: 70 % - - -This plugin let you provision your users and groups from an external identity provider using the `SCIM `_ protocol. The update from the directory to GLPI is done “just in time”. -Each modification is done on the fly, without any cron. GLPI is the service provider, and the directory is the identity provider. - -**Warning, the SCIM API endpoint provided by the plugin must be accessible from the identity provider.** If we talk about Azure or Okta, this particular url should be available from the internet. We suggest strongly to limit the ip addresses that can access this url (in addition of adding a strong authentication method). - -.. _setup_scim: - -Setup ------ - -You must declare an identity server in the plugin configuration (You can add any number). -Go to **Setup** > **SCIM Identity servers** menu and click the **[+ Add]** button on top of the page. - -.. figure:: pics/identity_server.png - :alt: SCIM configuration - :scale: 40 % - -Fill at least: - -- The name of the server, -- the user applied on GLPI when receiving a request (this will identify the user in th GLPI logs), -- check the “Active” field, -- and submit by clicking the [+ Add] button at the bottom of the form. - -You’ll be given an API url you may paste into your identity provider configuration. Check `specific provider documentation <#providers>`_ for more details. - -You may set some optional parameters : - -- **Save requests in logs**: if checked, all requests will be saved in the “Historical” tab of your declared server. -- **Default server**: if checked, this server will be used by default without providing it’s id in the API Url. -- **Security**: a dropdown of available security methods. Currently implemented: - - - **None**: no security, anyone can access the API. - - **Basic**: HTTP Basic authentication. You must provide a username and a password. - - **Digest**: HTTP Digest authentication. You must provide a username and a password. - - **Bearer**: HTTP Bearer authentication. A long lived (10years) jwt token will be generated. - - **OAuth2**: OAuth2 authentication. You must provide at least a valid redirection uri. We support the following flows: - - - Authorization code. - - Client credentials. - -Your SCIM server is now ready to receive requests from your identity provider. - -.. figure:: pics/scim_api.png - :alt: SCIM API example - :scale: 78 % - -Providers ---------- - -- :doc:`Azure ` -- :doc:`Okta ` - -A Note about passwords sync ---------------------------- - -Although it’s mentioned in the `SCIM specifications `_, password sync is not always available depending on the provider: - -- Azure: `not available `_ -- Okta: `available `_ - - -FAQ ---- - -If you have any questions about using the plugin, please consult `our FAQ `_ \ No newline at end of file +.. toctree:: + :maxdepth: 2 + + requirements + password_SSO + install_plugin + setup_plugin + entra + okta + faq \ No newline at end of file diff --git a/source/scim/install_plugin.rst b/source/scim/install_plugin.rst new file mode 100644 index 000000000..edcbd09b0 --- /dev/null +++ b/source/scim/install_plugin.rst @@ -0,0 +1,8 @@ +Install the plugin +------------------ + +- From the marketplace, download the **SCIM** plugin + +.. figure:: images/scim-1.png + :alt: Install the plugin + :scale: 100 % \ No newline at end of file diff --git a/source/scim/okta.rst b/source/scim/okta.rst index a7651cb10..eb515c068 100644 --- a/source/scim/okta.rst +++ b/source/scim/okta.rst @@ -1,63 +1,117 @@ -:orphan: - OKTA -==== +---- -References: ------------ +References +~~~~~~~~~~ - `Understanding SCIM `_ -- `Add SCIM provisioning to app integrations `_ -- `Assign applications to users `_ +- `Add SCIM provisioning to app integrations `_ +- `Assign applications to users `_ + -Setup ------ +Create application +~~~~~~~~~~~~~~~~~~ -After configuring the SCIM plugin, you can declare it in your Okta **Admin console**. -Go to the **Applications** > **Applications** menu and click on the “Create App Integration” button. -Choose **SWA - Secure Web Authentication** and click on the “Next” button. +- From your `OKTA portal `_ +- Click on **Applications** +- And **Create app integration** -.. figure:: pics/okta-1.png +.. figure:: images/scim-16.png :alt: Okta create app + :scale: 54 % + +- Select **SWA - Secure Web Authentication** + +.. figure:: images/scim-17.png + :alt: Select SWA Sign in + :scale: 78 % + +- Add a name to your application +- Add the URL of your GLPI instance (this will redirect your user to your GLPI if this application is avaiblable to the OKTA user portal) +- Click **Finish** + +.. figure:: images/scim-18.png + :alt: add integration + :scale: 97 % + +Setup the application +~~~~~~~~~~~~~~~~~~~~~ + +- Go back to **General** +- Click **Edit** +- Name the label +- Select SCIM to activate the service +- Click **Save** + +.. figure:: images/scim-19.png + :alt: setup general + :scale: 100 % + +To setup the provisioning, you need to setup GLPI. Refer to `setup GLPI `_ to configure **URL API** and **JWT Token** + +- Copy the **API URL** and the **JWT token**, you need to paste this information in OKTA. + + + +- Go back to your OKTA application +- Paste the API URL +- Select the Unique identifier field for users (*name.familyName, phoneNumber, name.givenName, id, userName, email,* etc. This will be the method to authenticate the users) +- Select the actions which can be supported +- Select **HTTP Header** +- Paste the **JWT token** + +.. Important:: + You need to **paste the JWT token** not the secret + +.. figure:: images/scim-21.png + :alt: setup provisionning + :scale: 67 % + +- Click **Test Connector Configuration** -Fill the form with the following values (you may adapt depending on your context): +.. figure:: images/scim-22.png + :alt: Test connection + :scale: 100 % -- **App name**: GLPI -- **App’s login page URL**: the index page of your glpi -- **App logo**: provide a logo picture -- **App type**: check “This is an internal app that we have created” +- you can now **close** this window and **save** your configuration -Let the other fields as default and click on the “Finish” button. +- Always in **provisioning**, you can edit and select the possible actions for updating your user data. -.. figure:: pics/okta-2.png - :alt: Okta setup app fields +.. Warning:: + We recommand to unselect **Sync Password** and use `OAuth SSO `_ to authenticate your user. -After the application has been created, you’ll be redirected to the **General Settings** tab. -You must edit the **App settings** section and check the **Enable SCIM provisioning** before saving your changes. +.. figure:: images/scim-23.png + :alt: Enable update data + :scale: 67 % -A new tab named **Provisioning** will appear. Click on it. +The last step is to assign your application to users -Edit the **SCIM Connection** section and fill the following fields: +Synchronising all users +~~~~~~~~~~~~~~~~~~~~~~~ -- **SCIM connector base URL**: the API url of your SCIM server you copied from the :ref:`plugin configuration `. -- **Unique identifier field for users**: ``id`` -- Check all fields in the **Supported provisioning actions** section **EXCEPT “Import Groups” one** -- Choose the **Authentication mode** you configured in the :ref:`plugin configuration `. +- Go to admin console +- Select **Directory > Groups** +- Select **Everyone** +- In **Applications**, click **Assign applications** +- Click on assign on your SCIM application +- Click **Save and Go Back** -You can test you configuration and then save your changes. +.. figure:: images/scim-24.png + :alt: assign everyone + :scale: 100 % -.. figure:: pics/okta-3.png - :alt: Okta SCIM configuration -Final steps, you must assign your application to your users: +Synchronising selected groups and users +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -1. In the Admin Console, go to **Directory** > **People**. -2. Click a user name in the Person & Username column. -3. Select the Applications tab. -4. Click Assign Applications. -5. Select applications from the list or enter the application name in the Search field. -6. Click [Assign] button. +- Go to admin console +- Select **Directory > People** +- Select the **User** you want to import +- In **Applications**, click **Assign applications** +- Click on assign on your SCIM application +- Click **Save and Go Back** -You’re done, your users will be provisioned in GLPI when they log in. +Repeat this step for all users and groups you want to import. -**NOTE**, it seems OKTA doesn’t give any automatic way to assign users to an application. +.. Important:: + See the procedure for setting up the `OAuth SSO `_ plugin to authenticate users in GLPI. \ No newline at end of file diff --git a/source/scim/password_SSO.rst b/source/scim/password_SSO.rst new file mode 100644 index 000000000..4c771838c --- /dev/null +++ b/source/scim/password_SSO.rst @@ -0,0 +1,10 @@ +Password/SSO +------------ + +Although it’s mentioned in the `SCIM specifications `_, password sync is not always available depending on the provider: + +- Azure: `not available `_ +- Okta: `available `_ + +.. Attention:: + Instead of pushing passwords, we strongly recommend that you use `OAuth SSO `_ to connect your users to GLPI \ No newline at end of file diff --git a/source/scim/pics/scim_api.png b/source/scim/pics/scim_api.png deleted file mode 100644 index d144de02a..000000000 Binary files a/source/scim/pics/scim_api.png and /dev/null differ diff --git a/source/scim/requirements.rst b/source/scim/requirements.rst new file mode 100644 index 000000000..bdbd837dd --- /dev/null +++ b/source/scim/requirements.rst @@ -0,0 +1,16 @@ +Requirements (on-premise) +------------------------- + +============ =========== =========== +GLPI Version Minimum PHP Recommended +============ =========== =========== +10.0.x 8.1 8.2 +============ =========== =========== + +.. note:: + A `basic licence `_ (or higher) is required. This plugin is also available from the `Cloud `_. + + +.. important:: + The SCIM API endpoint provided by the plugin must be accessible from the identity provider. If we talk about Azure or Okta, this particular URL should be available from the internet. We suggest strongly to limit the IP addresses that can access this URL (in addition of adding a strong authentication method). + diff --git a/source/scim/setup_plugin.rst b/source/scim/setup_plugin.rst new file mode 100644 index 000000000..0e82c7c70 --- /dev/null +++ b/source/scim/setup_plugin.rst @@ -0,0 +1,51 @@ +Setup GLPI +---------- + +You must declare an identity server in the plugin configuration (You can add any number). + +- Go to your instance GLPI +- Select **Setup > SCIM Identity servers** +- Click **+ Add** +- Add a name +- Select the admin account who can update your GLPI's datas +- Click **Activate** +- Select the **Baerer** method +- click **+ Add** +- You can see now the API URL + +.. figure:: images/scim-20.png + :alt: setup general + :scale: 45 % + +.. note:: For Azure, the awaited secret is a long life valid jwt token. + We cannot use an oauth exchange (Azure doesn’t ask for an authorize URL). + So in GLPI, setup you SCIM server with **Bearer** security and paste the JWT token from GLPI in the **Secret token** field of Azure. + + +.. Warning:: Make sure you **paste the token (Jwt token)** to ensure your application works properly. + +You’ll be given an API URL you may paste into your identity provider configuration. Check the `specific provider documentation <#providers>`_ for more details. + + +You may set some optional parameters : + +- **Save requests in logs**: if checked, all requests will be saved in the “Historical” tab of your declared server. +- **Default server**: if checked, this server will be used by default without providing it’s ID in the API URL. + +- **Security**: a dropdown of available security methods. Currently implemented: + + - **None**: no security, anyone can access the API. + - **Basic**: HTTP Basic authentication. You must provide a username and a password. + - **Digest**: HTTP Digest authentication. You must provide a username and a password. + - **Bearer**: HTTP Bearer authentication. A long lived (10 years) JWT token will be generated. + - **OAuth2**: OAuth2 authentication. You must provide at least a valid redirection URI. We support the following flows: + + + - Authorization code. + - Client credentials. + +Your SCIM server is now ready to receive requests from your identity provider. + +.. figure:: images/scim_api.png + :alt: SCIM API example + :scale: 78 %