Authenticate to Jira using OAuth

You can use OAuth to authenticate to Jira from Dimensions CM.

OAuth enables 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.

Note: Before users register their Jira credentials, you can customize the password for encrypting Jira credentials in a Dimensions CM database. For details, see Secure Jira credentials.

Generate custom certificates

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.

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. Run 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):

    Copy code 
    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

  3. Merge the certificate and encrypted private key into a single server.pem file:

    Windows:

    Copy code 
    copy /b servercert.pem + serverkey.pem server.pem
    openssl x509 -subject -issuer -noout -in server.pem

     

    UNIX:

    Copy code 
    cat servercert.pem serverkey.pem > server.pem

This process is the same as generating certificates for using SDP over SSL. For details, see Administration.

Back to top

Use 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 this folder: %DM_ROOT%\dfs\server.pem.
  2. Open the Dimensions CM server %DM_ROOT%\dm.cfg configuration file.

  3. To map Jira request providers to certificate files, add this variable:

    Copy code 
    DM_JIRA_KEY_PRODUCTION <certificate file>

    Example: If your Jira provider has the ID PRODUCTION:

    # Provider with the ID 'PRODUCTION' uses this certificate
    DM_JIRA_KEY_PRODUCTION server.pem

  4. If you specified a private key password while generating a certificate, run the dmpasswd utility to register the password:

    Copy code 
    dmpasswd DM_JIRA_KEY_PASSWORD_PRODUCTION -add

  5. Add the password variable with the special $$DMSECURE$$ value:

    Copy code 
    DM_JIRA_KEY_PASSWORD_PRODUCTION $$DMSECURE$$

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

    Copy code 
    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_*

  6. Restart the Dimensions CM listener service.

Back to top

Use custom certificate for all instances

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

Copy code 
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

Set 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 in to 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 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 in to 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.
    1. Log in to the Administration Console.
    2. In the Database Management section, select Request providers. The Request Providers page opens.
    3. In the navigation pane, expand the Jira node and select a Jira request provider.
    4. In the content pane, in the General section, click the Edit button. The Edit Request Provider dialog box opens.
    5. To view connection details, click Next.
    6. Click Copy Public Key next to the Consumer Key field. The key is copied to your clipboard.
  12. Click OK.

Back to top

See also: