Getting Started

Getting Started#

If you have not already done so, create/activate a virtualenv. Unless otherwise stated, assume all terminal code below is executed within the virtualenv.

Install dependencies#

Dependencies can be installed via the command below.

$ make requirements

Local/Private Settings#

When developing locally, it may be useful to have settings overrides that you do not wish to commit to the repository. If you need such overrides, create a file credentials/settings/private.py. This file’s values are read by credentials/settings/local.py, but ignored by Git.

Configure the Amazon S3 Storage Backend#

When you deploy the credentials on a staging or production server, you must change the settings to use the Amazon S3 storage backend instead of Django’s default file storage backend (django.core.files.storage.FileSystemStorage) so that you do not commit changes to the repository.

To change the settings, SSH into the system, and then update the /edx/etc/credentials.yml file. This file’s values are read by credentials/settings/production.py, but ignored by Git.

The following example shows how to use the Amazon S3 storage backend:

AWS_STORAGE_BUCKET_NAME: credentials-s3-bucket-name
AWS_ACCESS_KEY_ID: AAAAAAAAAAAAAAA
AWS_SECRET_ACCESS_KEY: BBBBBBBBBBBBBBBBBBBB
AWS_DEFAULT_ACL: ''

Configure edX OAuth#

This service relies on the LMS serves as the OAuth 2.0 authentication provider.

Configuring credentials to work with OAuth requires registering a new client with the authentication provider and updating the Django settings for this project with the client credentials.

A new OAuth 2.0 client can be created at http://localhost:18000/admin/oauth2_provider/application/.

  1. Click the Add Application button.

  2. Leave the user field blank.

  3. Specify the name of this service, credentials, as the client name.

  4. Set the URL to the root path of this service: http://localhost:8150/.

  5. Set the Redirect URL to the complete endpoint: http://localhost:18150/complete/edx-oauth2/.

  6. Copy the Client ID and Client Secret values. They will be used later.

  7. Select Confidential as the client type.

  8. Select Authorization code as the authorization grant type.

  9. Click Save.

Now that you have the client credentials, you can update your settings (ideally in credentials/settings/local.py). The table below describes the relevant settings.

Setting

Description

Value

SOCIAL_AUTH_EDX_OAUTH2_KEY

OAuth 2.0 client key

(This should be set to the value generated when the client was created.)

SOCIAL_AUTH_EDX_OAUTH2_SECRET

OAuth 2.0 client secret

(This should be set to the value generated when the client was created.)

SOCIAL_AUTH_EDX_OAUTH2_URL_ROOT

OAuth 2.0 authentication URL

http://127.0.0.1:18000/oauth2

Service User#

The Open edX Credentials service must communicate with other Open edX services, such as the LMS or Platform services. Because certificates are publicly accessible, edX provides a “Credentials service user” account that uses JWT authentication to communicate between the Credentials service and other Open edX services. The Credentials service user makes requests on behalf of the Credentials service to access required APIs and fetch data. The Credentials service user is only available for internal use in Open edX services.

By default, the username for the Credentials service user is credentials_service_user. You can change the username of the Credentials service user in the CREDENTIALS_SERVICE_USER configuration setting. However, the Credentials service assumes that a service user named credentials_service_user is present in all needed services.

The Credentials service user must have the following characteristics.

  • The service user must have the Admin role.

  • The service user must have a password that is very difficult to guess so that the account cannot be accessed from web interfaces.

  • The service user must be available in all of the services that the Credentials service must communicate with if these services do not require real user names.

Run migrations#

Local installations use SQLite by default. If you choose to use another database backend, make sure you have updated your settings and created the database (if necessary). Migrations can be run with Django’s migrate command.

$ python manage.py migrate

Run the server#

The server can be run with Django’s runserver command. If you opt to run on a different port, make sure you update OAuth2 client via LMS admin.

$ python manage.py runserver 8150
Contents