{"id":22268231,"url":"https://github.com/curityio/box-authenticator","last_synced_at":"2025-03-25T14:45:53.740Z","repository":{"id":27904321,"uuid":"114264283","full_name":"curityio/box-authenticator","owner":"curityio","description":"Box oauth authenticator that can be used with any Java-based Web API","archived":false,"fork":false,"pushed_at":"2022-05-12T13:09:32.000Z","size":382,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-01-30T13:31:53.656Z","etag":null,"topics":["authenticator","box","java","login","oauth","plugin"],"latest_commit_sha":null,"homepage":"https://curity.io/resources/learn/box-authenticator/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/curityio.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-12-14T15:07:52.000Z","updated_at":"2023-04-26T13:36:32.000Z","dependencies_parsed_at":"2022-08-09T02:00:05.092Z","dependency_job_id":null,"html_url":"https://github.com/curityio/box-authenticator","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/curityio%2Fbox-authenticator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/curityio%2Fbox-authenticator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/curityio%2Fbox-authenticator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/curityio%2Fbox-authenticator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/curityio","download_url":"https://codeload.github.com/curityio/box-authenticator/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245486243,"owners_count":20623239,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["authenticator","box","java","login","oauth","plugin"],"created_at":"2024-12-03T11:11:59.537Z","updated_at":"2025-03-25T14:45:53.708Z","avatar_url":"https://github.com/curityio.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"Box Authenticator Plug-in\n=========================\n   \n.. image:: https://img.shields.io/badge/quality-demo-red\n       :target: https://curity.io/resources/code-examples/status/\n       \n.. image:: https://img.shields.io/badge/availability-source-blue\n       :target: https://curity.io/resources/code-examples/status/\n\nThis project provides an opens source Box 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 Box credentials. The app that integrates with Curity may also be configured to receive the Box access token and refresh token, allowing it to manage resources in a Box enterprise.\n\nSystem Requirements\n~~~~~~~~~~~~~~~~~~~\n\n* Curity Identity Server and `its system requirements \u003chttps://developer.curity.io/docs/latest/system-admin-guide/system-requirements.html\u003e`_\n\nRequirements for Building from Source\n\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\n\n* Maven 3\n* Java SDK 17\n\nCompiling the Plug-in from Source\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe source is very easy to compile. To do so from a shell, issue this command: ``mvn package``.\n\nInstallation\n~~~~~~~~~~~~\n\nTo install this plug-in, either download a binary version available from the `releases section of this project's GitHub repository \u003chttps://github.com/curityio/box-authenticator/releases\u003e`_ 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/box``. (The name of the last directory, ``box``, 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.\n\n.. note::\n\n    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.\n\nFor a more detailed explanation of installing plug-ins, refer to the `Curity developer guide \u003chttps://developer.curity.io/docs/latest/developer-guide/plugins/index.html#plugin-installation\u003e`_.\n\nCreating an App in Box\n~~~~~~~~~~~~~~~~~~~~~~\n\nAs `described in the Box documentation \u003chttps://developer.box.com/docs/getting-started-box-integration\u003e`_, you can `create different kinds of apps \u003chttps://app.box.com/developers/console/newapp\u003e`_ that use the Box APIs. When using this plug-in, create a new ``Enterprise Integration``, as shown in the following figure:\n\n.. figure:: docs/images/new-box-app.png\n    :name: new-box-app\n    :align: center\n    :width: 500px\n\n    Creating a new Box Enterprise Integration application\n\nThe authentication method, as shown in the following figure, should be ``Standard OAuth 2.0 (User Authentication)``:\n\n.. figure:: docs/images/box-authentication-method.png\n    :align: center\n    :width: 500px\n\n    Selecting to authenticate users in the new app\n\nThen, give the app a name, e.g., ``Curity-Enterprise-Integration-App``.\n\nWhen you view the app's configuration after creating it, you'll find the ``Client ID`` and ``Client Secret``. These will be needed later when configuring the plug-in in Curity.\n\nBox will also display the redirect URI in the new app's configuration. This needs to match the yet-to-be-created Box 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/$boxAuthnticatorId/callback``, where each of these URI components has the following meaning:\n\n============================== =========================================================================================\nURI Component                  Meaning\n------------------------------ -----------------------------------------------------------------------------------------\n``baseUrl``                    The base URL of the server (defined on the ``System --\u003e General`` page of the\n                               admin GUI). If this value is not set, then the server scheme, name, and port should be\n                               used (e.g., ``https://localhost:8443``).\n``authenticationEndpointPath`` The path of the authentication endpoint. In the admin GUI, this is located in the\n                               authentication profile's ``Endpoints`` tab for the endpoint that has the type\n                               ``auth-authentication``.\n``boxAuthenticatorId``         This is the name given to the Box authenticator when defining it (e.g., ``box1``).\n============================== =========================================================================================\n\nOnce the redirect URI is updated, the only thing left is to configure scopes. You need to configure at least one scope `Manage User`.\n\n.. figure:: docs/images/box-scope-manage-user.png\n    :align: center\n    :width: 500px\n\n\nIt could be helpful to also enable additional scopes. Scopes are the Box-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 Box API, additional scopes probably should be enabled. Refer to the `Box documentation on scopes \u003chttps://developer.box.com/docs/authentication#section-oauth-2-scopes\u003e`_ for an explanation of those that can be enabled and what they allow.\n\n.. warning::\n\n    If the app configuration in Box does not allow a certain scope (e.g., the ``Manage Webhooks`` 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.\n\nCreating a Box Authenticator in Curity\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe easiest way to configure a new Box 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.\n\n1. Go to the ``Authenticators`` page of the authentication profile wherein the authenticator instance should be created.\n2. Click the ``New Authenticator`` button.\n3. Enter a name (e.g., ``box1``). This name needs to match the URI component in the callback URI set in the Box app.\n4. For the type, pick the ``Box`` option:\n\n    .. figure:: docs/images/box-authenticator-type-in-curity.png\n        :align: center\n        :width: 600px\n\n5. 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 Box-specific options can be found.\n\n    .. note::\n\n        The Box-specific configuration is generated dynamically based on the `configuration model defined in the Java interface \u003chttps://github.com/curityio/box-authenticator/blob/master/src/main/java/io/curity/identityserver/plugin/box/config/BoxAuthenticatorPluginConfig.java\u003e`_.\n\n6. 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 Box OAuth server's token and user info endpoints. To define this, do the following:\n\n    A. click the ``Facilities`` button at the top-right of the screen.\n    B. Next to ``HTTP``, click ``New``.\n    C. Enter some name (e.g., ``boxClient``).\n    D. Toggle on the ``Use Truststore`` option and click ``Apply``.\n\n        .. figure:: docs/images/box-http-client.png\n            :align: center\n            :width: 400px\n\n7. Back in the Box authenticator instance that you started to define, select the new HTTP client from the dropdown.\n\n    .. figure:: docs/images/http-client.png\n\n8. Also in the ``Facilities`` view, you probably need to add the intermediary Certificate Authority (CA) used to sign the SSL certificate on Box's token and user info endpoints. (You'll get a server error and find a PKIX-related message in the server log when attempting to login with the Box authenticator if this is necessary.) To do this, perform the following steps:\n\n    A. Click ``Facilities``.\n    B. Next to ``Server Trust Stores``, click ``New``.\n    C. Enter the text of the intermediary CA and give it a name (e.g., ``Box_Intermediate_CA``). Currently, the certificate of this CA is this:\n\n        .. code-block::\n\n            -----BEGIN CERTIFICATE-----\n            MIIDVDCCAjygAwIBAgIDAjRWMA0GCSqGSIb3DQEBBQUAMEIxCzAJBgNVBAYTAlVT\n            MRYwFAYDVQQKEw1HZW9UcnVzdCBJbmMuMRswGQYDVQQDExJHZW9UcnVzdCBHbG9i\n            YWwgQ0EwHhcNMDIwNTIxMDQwMDAwWhcNMjIwNTIxMDQwMDAwWjBCMQswCQYDVQQG\n            EwJVUzEWMBQGA1UEChMNR2VvVHJ1c3QgSW5jLjEbMBkGA1UEAxMSR2VvVHJ1c3Qg\n            R2xvYmFsIENBMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA2swYYzD9\n            9BcjGlZ+W988bDjkcbd4kdS8odhM+KhDtgPpTSEHCIjaWC9mOSm9BXiLnTjoBbdq\n            fnGk5sRgprDvgOSJKA+eJdbtg/OtppHHmMlCGDUUna2YRpIuT8rxh0PBFpVXLVDv\n            iS2Aelet8u5fa9IAjbkU+BQVNdnARqN7csiRv8lVK83Qlz6cJmTM386DGXHKTubU\n            1XupGc1V3sjs0l44U+VcT4wt/lAjNvxm5suOpDkZALeVAjmRCw7+OC7RHQWa9k0+\n            bw8HHa8sHo9gOeL6NlMTOdReJivbPagUvTLrGAMoUgRx5aszPeE4uwc2hGKceeoW\n            MPRfwCvocWvk+QIDAQABo1MwUTAPBgNVHRMBAf8EBTADAQH/MB0GA1UdDgQWBBTA\n            ephojYn7qwVkDBF9qn1luMrMTjAfBgNVHSMEGDAWgBTAephojYn7qwVkDBF9qn1l\n            uMrMTjANBgkqhkiG9w0BAQUFAAOCAQEANeMpauUvXVSOKVCUn5kaFOSPeCpilKIn\n            Z57QzxpeR+nBsqTP3UEaBU6bS+5Kb1VSsyShNwrrZHYqLizz/Tt1kL/6cdjHPTfS\n            tQWVYrmm3ok9Nns4d0iXrKYgjy6myQzCsplFAMfOEVEiIuCl6rYVSAlk6l5PdPcF\n            PseKUgzbFbS9bZvlxrFUaKnjaZC2mqUPuLk/IH2uSrW4nOQdtqvmlKXBx4Ot2/Un\n            hw4EbNX/3aBd7YdStysVAq45pmp06drE57xNNB6pXE0zX5IJL4hmXXeXxx12E6nV\n            5fEWCRE11azbJHFwLJhWC9kXtNHjUStedejV0NxPNO3CBWaAocvmMw==\n            -----END CERTIFICATE-----\n\n    D. If you have downloaded it, browse to the file. In any case, click the ``Add`` button.\n\n9. In the ``Client ID`` textfield, enter the client ID from the Box app configuration. This is the auto-generated ID that was shown after picking the app type and authentication method.\n10. Also enter the matching ``Client Secret``.\n11. If you have enabled any scopes or wish to limit the scopes that Curity will request of Box, toggle on the desired scopes (e.g., ``Enterprise Properties`` or ``Manage Groups``).\n\nOnce 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``.\n\nOnce the configuration is committed and running, the authenticator can be used like any other.\n\nPassing Box's Tokens Downstream\n\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\n\nWhen using the Box authenticator together with an OpenID Connect Relying Party app (i.e., a client), it can be helpful to pass along Box's access token and refresh token. This will allow the app to make calls to Box's APIs. To do this, a custom procedure has to be created that relays the tokens; otherwise, they'll be dropped. To do this, follow these steps in the OAuth profile that is associated with the authentication profile where the Box authenticator was defined:\n\n1. Click on ``Endpoints``.\n2. Find the one of type ``oauth-authorize`` and select a procedure from the ``Authorize Authorization Code`` dropdown.\n3. Click the ``Edit`` button.\n4. In the script editor that opens, enter the following script:\n\n    .. code-block:: javascript\n\n        function result(context) {\n            var authorizationCodeData = context.getDefaultAuthorizationCodeData();\n            var contextAttributes = context.contextAttributes();\n\n            authorizationCodeData.box_access_token = contextAttributes.box_access_token;\n            authorizationCodeData.box_refresh_token = contextAttributes.box_refresh_token;\n\n            var issuedAuthorizationCode = context.authorizationCodeIssuer.issue(authorizationCodeData);\n\n            return {\n                code: issuedAuthorizationCode,\n                state: context.providedState\n            };\n        }\n\n    In this script, the context attributes are retrieved. These are the ones that `the plug-in adds \u003chttps://github.com/curityio/box-authenticator/blob/master/src/main/java/io/curity/identityserver/plugin/box/authentication/CallbackRequestHandler.java#L189\u003e`_. From these, the Box access and refresh tokens are stored with the nonce that the Curity OAuth server issues.\n\n5. When this code is redeemed, these will be available in the context of subsequent scripts that run. For instance, if a downstream app is integrating with Curity using the code flow, then the ``Token Authorization Code`` procedure on the ``oauth-token`` endpoint should be customized. This procedure may pass on Box's tokens to the client in the ID token (if the app is allowed to use the ``openid`` scope and OpenID Connect is enabled in the profile) and/or to the API in the access token. The following script passes on Box's tokens to both the app and the back-end API:\n\n    .. code-block:: javascript\n\n        function result(context) {\n            var delegationData = context.getDefaultDelegationData();\n            var nonceData = context.presentedNonce.data\n\n            var issuedDelegation = context.delegationIssuer.issue(delegationData);\n            var accessTokenData = context.getDefaultAccessTokenData();\n\n            accessTokenData.box_access_token = nonceData.box_access_token;\n            accessTokenData.box_refresh_token = nonceData.box_refresh_token\n\n            var issuedAccessToken = context.accessTokenIssuer.issue(accessTokenData, issuedDelegation);\n\n            var refreshTokenData = context.getDefaultRefreshTokenData();\n            var issuedRefreshToken = context.refreshTokenIssuer.issue(refreshTokenData, issuedDelegation);\n\n            var responseData = {\n                access_token: issuedAccessToken,\n                refresh_token: issuedRefreshToken,\n                token_type: 'bearer',\n                expires_in: secondsUntil(accessTokenData.exp)\n            };\n\n            if (context.scopeNames.contains('openid')) {\n                var idTokenData = context.getDefaultIdTokenData();\n                var idTokenIssuer = context.idTokenIssuer;\n\n                idTokenData.box_access_token = nonceData.box_access_token;\n                idTokenData.box_refresh_token = nonceData.box_refresh_token;\n                idTokenData.at_hash = idTokenIssuer.atHash(issuedAccessToken);\n\n                responseData.id_token = idTokenIssuer.issue(idTokenData);\n            }\n\n            return responseData;\n        }\n\n    Here, the ``context`` object has a property called ``presentedNonce``. This is the authorization code presented to Curity's token endpoint. The Box tokens were associated with this by the previous procedure. These are added to the ``accessTokenData`` that is the input of the ``accessTokenIssuer``. This will mean that Curity's access token (whether it is a JWT or an opaque GUID) will include Box's. This will allow the back-end APIs to call Box's APIs. Box's tokens are also included in the ``idTokenData`` that is used when issuing an ID token to the app.\n\nLicense\n~~~~~~~\n\nThis plugin and its associated documentation is listed under the `Apache 2 license \u003cLICENSE\u003e`_.\n\nMore Information\n~~~~~~~~~~~~~~~~\n\nPlease visit `curity.io \u003chttps://curity.io/\u003e`_ for more information about the Curity Identity Server.\n\nCopyright (C) 2017 Curity AB.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcurityio%2Fbox-authenticator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcurityio%2Fbox-authenticator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcurityio%2Fbox-authenticator/lists"}