If your SaaS product is built with Python’s Django web framework and you want to incorporate WorkOS’ Admin Portal functionality, you can do a dry-run of the Admin Portal integration on our example Django app which makes use of the WorkOS Python SDK.
1. In your CLI, navigate to the directory into which you want to clone this git repo.
2. Clone this git repo using your preferred secure method (HTTPS or SSH).
3. Navigate to the cloned repo.
4. Create and source a Python virtual environment. You should then see (env) at the beginning of your command-line prompt.
5. Navigate to the workos_django directory and install the cloned app's dependencies. (Note: There are two nested workos_django directories in this repo; ensure you're in the top level directory that includes the manage.py file.)
6. Obtain and make note of the following values. In the next step, these will be set as environment variables.
- Your WORKOS_API_KEY
- Your WORKOS_CLIENT_ID, in the format client_<random-alphanumeric-string>, retrievable from the WorkOS dashboard under the Configuration tab.
7. Ensure you're in the root app directory for the example app, workos_django/, where the manage.py file resides. Create a .env file to securely store the environment variables. Open this file with the Nano text editor. (This file is listed in this repo's .gitignore file, so your sensitive information will not be checked into version control.)
8. Once the Nano text editor opens, you can directly edit the .env file by listing the environment variables:
To exit the Nano text editor, type CTRL + x. When prompted to "Save modified buffer", type Y, then press the Enter or Return key.
9. Source the environment variables so they are accessible to the operating system.
You can ensure the environment variables were set correctly by running the following commands. The output should match the corresponding values.
10. Run the Django migrations. Again, ensure you're in the workos_django/ directory where the manage.py file is.
You should see output like:
11. Update the Admin Portal Redirect Link in the Configuration page of your WorkOS Dashboard as shown below. The URL should be http://localhost:8000.
After an Admin Portal user creates an SSO connection using the Admin Portal, they need to be redirected to a webpage within your application (usually this webpage confirms successful creation of the connection). To configure which webpage this is, enter the webpage’s URL in the Configuration section of your WorkOS dashboard under the “Admin Portal Redirect Link” header. For production usage this URL must begin with HTTPS, but for development purposes the URL can begin with HTTP.
12. We need to be able to serve static files in development while still having `debug=True` in the settings.py file. We also need to be able to send requests to WorkOS which typically isn’t possible when `debug=True`, but we can include the `--insecure` flag when starting the server locally to accomplish this.
You'll know the server is running when you see no errors in the CLI, and output similar to the following is displayed:
13. Once the server is running, navigate to http://localhost:8000 to view the homepage of the example Django app. Enter the name of the new Organization to be created and the names of all of the Organization's associated domains.
14. Click on the button to create your Organization and log in to the Admin Portal workflow! You'll be taken to the page shown below.
Congratulations! You just added the WorkOS Admin Portal to your Django app.
When you clone this repo, the DEBUG setting is False by default in app.py. You can set DEBUG = True if you need to troubleshoot something during the tutorial, but you must use DEBUG = False in order to successfully connect to the WorkOS API.
If you get stuck and aren't able to resolve the issue by reading our API reference or tutorials, please reach out to us at [email protected] so we can help.