Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/curityio/salesforce-authenticator

Salesforce oauth authenticator that can be used with any Java-based Web API
https://github.com/curityio/salesforce-authenticator

authenticator java oauth2 openidconnect plugin salesforce

Last synced: about 3 hours ago
JSON representation

Salesforce oauth authenticator that can be used with any Java-based Web API

Awesome Lists containing this project

README 

        
Salesforce Authenticator Plug-in

================================



.. image:: https://travis-ci.org/curityio/salesforce-authenticator.svg?branch=master

       :target: https://travis-ci.org/curityio/salesforce-authenticator

       

.. image:: https://img.shields.io/badge/quality-demo-red

    :target: https://curity.io/resources/code-examples/status/



.. image:: https://img.shields.io/badge/availability-source-blue

    :target: https://curity.io/resources/code-examples/status/



This project provides an opens source Salesforce Authenticator plug-in for the Curity Identity Server. This allows an administrator to add functionality to Curity which will then enable end users to login using their Salesforce credentials. The app that integrates with Curity may also be configured to receive the Salesforce access token and refresh token, allowing it to manage resources in Salesforce.



System Requirements

~~~~~~~~~~~~~~~~~~~



* Curity Identity Server 7.0.2 and `its system requirements `_



Requirements for Building from Source

"""""""""""""""""""""""""""""""""""""



* Maven 3

* Java SDK 17 or later



Compiling the Plug-in from Source

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~



The source is very easy to compile. To do so from a shell, issue this command: ``mvn package``.



Installation

~~~~~~~~~~~~



To install this plug-in, either download a binary version available from the `releases section of this project's GitHub repository `_ or compile it from source (as described above). If you compiled the plug-in from source, the package will be placed in the ``target`` subdirectory. The resulting JAR file or the one downloaded from GitHub needs to placed in the directory ``${IDSVR_HOME}/usr/share/plugins/salesforce``. (The name of the last directory, ``salesforce``, which is the plug-in group, is arbitrary and can be anything.) After doing so, the plug-in will become available as soon as the node is restarted.



.. note::



The JAR file needs to be deployed to each run-time node and the admin node. For simple test deployments where the admin node is a run-time node, the JAR file only needs to be copied to one location.



For a more detailed explanation of installing plug-ins, refer to the `Curity developer guide `_.



Creating an App in Salesforce

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~



`Setting up OAuth 2.0 `_ requires that you take some steps within Salesforce and in other locations. If any of the steps are unfamiliar,

 see `Understanding Authentication `_.



Create a connected app if you haven’t already done so.



* In Salesforce Classic, from Setup, enter Apps in the Quick Find box, select **Apps** (under **Build** | **Create**), then click the name of the connected app.

* In Lightning Experience, from Setup, enter Apps in the Quick Find box, select App Manager, click Action dropdown, and then select Edit.



    .. figure:: docs/images/create-salesforce-app.png

        :name: doc-create-salesforce-app.png-app

        :align: center

        :width: 500px



When you click Save, the ``Consumer Key`` is created and displayed, and a ``Consumer Secret`` is created (click the link to reveal it).

The ``Consumer Key`` and ``Consumer Secret`` refers to ``Client ID`` and ``Client Secret`` respectively.



Click **Enable OAuth Settings** and specify your callback URL and OAuth scopes. The Callback URL need to match the yet-to-be-created Salesforce authenticator instance in Curity.

The default will not work, and, if used, will result in an error. This should be updated to some URL that follows the pattern ``$baseUrl/$authenticationEndpointPath/$salesforceAuthnticatorId/callback``, where each of these URI components has the following meaning:



============================== ============================================================================================

URI Component                  Meaning

------------------------------ --------------------------------------------------------------------------------------------

``baseUrl``                    The base URL of the server (defined on the ``System --> General`` page of the

                               admin GUI). If this value is not set, then the server scheme, name, and port should be

                               used (e.g., ``https://localhost:8443``).

``authenticationEndpointPath`` The path of the authentication endpoint. In the admin GUI, this is located in the

                               authentication profile's ``Endpoints`` tab for the endpoint that has the type

                               ``auth-authentication``.

``salesforceAuthenticatorId``  This is the name given to the Salesforce authenticator when defining it

                               (e.g., ``salesforce1``).

============================== ============================================================================================



It could be helpful to also enable additional scopes. Scopes are the Salesforce-related rights or permissions that the app is requesting. If the final application (not Curity, but the downstream app) is going to perform actions using the Salesforce API, additional scopes probably should be enabled. Refer to the `Salesforce documentation on scopes `_ for an explanation of those that can be enabled and what they allow.



.. warning::



    If the app configuration in Salesforce does not allow a certain scope (e.g., the ``api`` scope) but that scope is enabled in the authenticator in Curity, a server error will result. For this reason, it is important to align these two configurations or not to define any when configuring the plug-in in Curity.



Creating a Salesforce Authenticator in Curity

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~



The easiest way to configure a new Salesforce authenticator is using the Curity admin UI. The configuration for this can be downloaded as XML or CLI commands later, so only the steps to do this in the GUI will be described.



1. Go to the ``Authenticators`` page of the authentication profile wherein the authenticator instance should be created.

2. Click the ``New Authenticator`` button.

3. Enter a name (e.g., ``salesforce1``). This name needs to match the URI component in the callback URI set in the Salesforce app.

4. For the type, pick the ``Salesforce`` option:



    .. figure:: docs/images/salesforce-authenticator-type-in-curity.png

        :align: center

        :width: 600px



5. On the next page, you can define all of the standard authenticator configuration options like any previous authenticator that should run, the resulting ACR, transformers that should executed, etc. At the bottom of the configuration page, the Salesforce specific options can be found.



        .. note::



The Salesforce specific configuration is generated dynamically based on the `configuration model defined in the Java interface `_.



6. Certain required and optional configuration settings may be provided. One of these is the ``HTTP Client`` setting. This is the HTTP client that will be used to communicate with the Salesforce OAuth server's token and user info endpoints. To define this, do the following:



    A. click the ``Facilities`` button at the top-right of the screen.

    B. Next to ``HTTP``, click ``New``.

    C. Enter some name (e.g., ``salesforceClient``).



        .. figure:: docs/images/salesforce-http-client.png

            :align: center

            :width: 400px



7. Back in the Salesforce authenticator instance that you started to define, select the new HTTP client from the dropdown.



        .. figure:: docs/images/http-client.png



8. In the ``Client ID`` textfield, enter the ``Consumer key`` from the Salesforce client app.

9. Also enter the matching ``Client Secret``.

10. If you wish to limit the scopes that Curity will request of Salesforce, toggle on the desired scopes (e.g., ``Chatter Api`` or ``Custom Permissions``).



Once all of these changes are made, they will be staged, but not committed (i.e., not running). To make them active, click the ``Commit`` menu option in the ``Changes`` menu. Optionally enter a comment in the ``Deploy Changes`` dialogue and click ``OK``.



Once the configuration is committed and running, the authenticator can be used like any other.



License

~~~~~~~



This plugin and its associated documentation is listed under the `Apache 2 license `_.



More Information

~~~~~~~~~~~~~~~~



Please visit `curity.io `_ for more information about the Curity Identity Server.



Copyright (C) 2018 Curity AB.