Using OAuth to authenticate to Jira

This topic describes how to use OAuth to authenticate to Jira from Dimensions CM.

OAuth allows a resource owner (a user) to grant access to their resource (for example, Jira) to a consumer (for example, Dimensions CM). The consumer can then make requests into Jira using OAuth. For more details see OAuth on the Atlassian web site.

OAuth processes uses private and public keys to secure the communication. By default, the certificate installed with Dimensions CM is used, so it is important to generate your own custom certificates.

Generating custom certificates

Use the openssl utility to generate custom self-signed certificates.

To generate custom certificates:

  1. Navigate to the following directory:
    • Windows: %DM_ROOT%\prog
    • UNIX: $DM_ROOT/prog
  2. Execute the following commands to generate a certificate with a 2048 bit key size signed by the SHA256 algorithm. Certificates are valid for 1825 days (5 years):
  3. set OPENSSL_CONF=%DM_ROOT%\prog\openssl.cnf

    openssl req -config openssl.cnf -newkey rsa:2048 -sha256 -keyout serverkey.pem -out serverreq.pem

    openssl x509 -req -in serverreq.pem -sha256 -extensions v3_ca -signkey serverkey.pem -out servercert.pem -days 1825

  4. Merge the certificate and encrypted private key into a single server.pem file :
  5. Windows:

    copy /b servercert.pem + serverkey.pem server.pem

    openssl x509 -subject -issuer -noout -in server.pem

    UNIX:

    cat servercert.pem serverkey.pem > server.pem

This process is the same as generating certificates for using SDP over SSL. See Configuring CM to use SDP over SSL in the Dimensions CMAdministration Guide.

Back to top

Using generated certificates

Configure a Dimensions CM server to use a custom certificate that you generated.

To use generated certificates:

  1. Copy the generated certificate (see above) to the this folder: %DM_ROOT%\dfs\server.pem
  2. Open the Dimensions CM server %DM_ROOT%\dm.cfg configuration file.
  3. To map Jira external request providers to certificate files, add this variable:
  4. DM_JIRA_KEY_PRODUCTION <certificate file>

    For instance, if your Jira provider has the ID PRODUCTION:

    # Provider with the ID 'PRODUCTION' uses this certificate

    DM_JIRA_KEY_PRODUCTION server.pem

  5. If you specified a private key password while generating a certificate, run the dmpasswd utility to register the password:
  6. dmpasswd DM_JIRA_KEY_PASSWORD_PRODUCTION -add

  7. Add the password variable with the special $$DMSECURE$$ value:
  8. DM_JIRA_KEY_PASSWORD_PRODUCTION $$DMSECURE$$

    You can specify the key password directly in dm.cfg, however this is less secure:

    DM_JIRA_KEY_PASSWORD_PRODUCTION <password>

    If a private key does not have a password, do not add variables that begin with: DM_JIRA_KEY_PASSWORD_*

  9. Restart the Dimensions CM listener service.

Back to top

Using a custom certificate for all request providers

You can use the same certificate for all providers. Add the DM_JIRA_KEY variable without the suffix _<ProviderID> to the Dimensions CM server configuration file (dm.cfg):

DM_JIRA_KEY <certificate file>

dmpasswd DM_JIRA_KEY_PASSWORD -add

DM_JIRA_KEY_PASSWORD $$DMSECURE$$

DM_JIRA_KEY_PASSWORD <password>

If a private key does not have a password, do not add variables that begin with: DM_JIRA_KEY_PASSWORD *

Back to top

Setting up application links in Jira

To use OAuth on Jira Software Cloud and Server, configure the incoming application link in Jira to make it a resource for Dimensions CM. Use custom certificates so that third party applications and other Dimensions CM instances cannot use the same application link to a Jira repository.

To set up application links to Jira:

  1. Log into a Jira Cloud or Jira Server account.
  2. Switch to Administration.
  3. In Application Settings click Jira.
  4. Select Products > Integration > Application links.
  5. For URL accept the default value and click Create new link.
  6. For Application Name enter a meaningful name for the link, for example: DimCM-MyProduct

  7. Select Create incoming link to enable Dimensions CM access to Jira (system administrator global permission is required).

  8. The other settings in the application link wizard are not required. Click Continue.
  9. Enter the Consumer Key, a unique mapping identifier between Dimensions CM and Jira instances. The consumer key can be any symbolic value but must be the same as the key in the Dimensions CM administration console Jira request provider, for example: cm_qlarius_cons_key

    Tip: The consumer key must be unique for each application link.

  10. Enter the Consumer Name, a value that is displayed to Dimensions CM users when they log into Jira from CM clients. Enter a meaningful name that is related to the current Dimensions CM product, for example: DimCM-MyProduct
  11. Enter the Public Key for the Jira application link.
  12. Click OK.

Back to top

See also: