|
| 1 | +# NetBox Enterprise SAML Configuration Guide |
| 2 | + |
| 3 | +## Required Information |
| 4 | + |
| 5 | +- **Entity ID**: This is your IdP's Entity ID obtained from the SAML metadata |
| 6 | +- **SSO URL**: Your IdP's SSO login URL |
| 7 | +- **x509 Certificate**: The Base64-encoded X.509 certificate used to sign SAML assertions |
| 8 | +- **NetBox Enterprise URL**: URL For the NetBox Enterprise instance |
| 9 | + |
| 10 | +## Generate Public and Private Keys |
| 11 | +These will be used later during configuration and can be generated from anywhere. Be sure to keep the private key secure. |
| 12 | + |
| 13 | +``` shell |
| 14 | +openssl genpkey -algorithm RSA -out saml_private_key.pem -pkeyopt rsa_keygen_bits:2048 |
| 15 | + |
| 16 | +openssl req -new -x509 -key saml_private_key.pem -out saml_cert.pem -days <specify number of days valid> |
| 17 | +``` |
| 18 | + |
| 19 | +## Configure the IdP |
| 20 | +Set up the IdP using the public key from the previous section, and the ACS URL (based on the NetBox Enterprise URL). These steps will vary depending on the IdP in use. |
| 21 | + |
| 22 | +**ACS URL**: "{NetBox Enterprise URL}/oauth/complete/saml/" |
| 23 | +**SP Entity ID**: "{NetBox Enterprise URL}" |
| 24 | + |
| 25 | +Example: |
| 26 | + |
| 27 | + |
| 28 | + |
| 29 | +### Configure Attributes or Claims |
| 30 | +Setup similar mappings in the IdP's "Attributes" or "Claims" section. Names may vary on different platforms. |
| 31 | + |
| 32 | +``` shell |
| 33 | +"attr_first_name": "first_name" |
| 34 | +"attr_last_name": "last_name" |
| 35 | +"attr_username": "email" |
| 36 | +"attr_email": "email" |
| 37 | +``` |
| 38 | + |
| 39 | +Example: |
| 40 | + |
| 41 | + |
| 42 | + |
| 43 | +### Capture x509 Certificate |
| 44 | +After setting up the IdP, generate a certificate in the IdP (this may be done by default). The x509 certificate can either be downloaded or viewed in the SAML metadata URL. This certificate data will be used in the next step. |
| 45 | + |
| 46 | +## Update NetBox Enterprise Config |
| 47 | +1. In the Admin Console for NetBox Enterprise, navigate to the **Config** tab and scroll to the bottom to check **Advanced Settings** |
| 48 | +2. Apply the following into **NetBox Python Configuration Overrides**, replacing the relevant information from previous steps. |
| 49 | + |
| 50 | +``` shell |
| 51 | +REMOTE_AUTH_ENABLED = True |
| 52 | +REMOTE_AUTH_AUTO_CREATE_USER = True |
| 53 | +REMOTE_AUTH_BACKEND = 'social_core.backends.saml.SAMLAuth' |
| 54 | +SOCIAL_AUTH_REDIRECT_IS_HTTPS = True |
| 55 | + |
| 56 | +SOCIAL_AUTH_SAML_SP_ENTITY_ID = "<NetBox Enterprise Instance URL>" |
| 57 | +SOCIAL_AUTH_SAML_SP_PUBLIC_CERT = "-----BEGIN CERTIFICATE-----<Public Key goes here>-----END CERTIFICATE-----" |
| 58 | +SOCIAL_AUTH_SAML_SP_PRIVATE_KEY = "-----BEGIN PRIVATE KEY-----<Private Key goes here>-----END PRIVATE KEY-----" |
| 59 | + |
| 60 | +SOCIAL_AUTH_SAML_ORG_INFO = { |
| 61 | + "en-US": { |
| 62 | + "name": "<Org Name>", |
| 63 | + "displayname": "<Org Display Name>", |
| 64 | + "url": "<Org Website>", |
| 65 | + } |
| 66 | +} |
| 67 | + |
| 68 | +SOCIAL_AUTH_SAML_TECHNICAL_CONTACT = { |
| 69 | + "givenName": "support", |
| 70 | + "emailAddress": "[<Support Email Address>](mailto:<Support Email Address>)" |
| 71 | +} |
| 72 | + |
| 73 | +SOCIAL_AUTH_SAML_SUPPORT_CONTACT = { |
| 74 | + "givenName": "support", |
| 75 | + "emailAddress": "[<Support Email Address>](mailto:<Support Email Address>)" |
| 76 | +} |
| 77 | + |
| 78 | +SOCIAL_AUTH_SAML_ENABLED_IDPS = { |
| 79 | + "idp": { |
| 80 | + "entity_id": "<SAML Entity ID>", |
| 81 | + "url": "<SAML Sign-on URL>", |
| 82 | + "x509cert": "<x509 Certificate>", |
| 83 | + "attr_user_permanent_id": "email", |
| 84 | + "attr_first_name": "first_name", |
| 85 | + "attr_last_name": "last_name", |
| 86 | + "attr_username": "email", |
| 87 | + "attr_email": "email", |
| 88 | + } |
| 89 | +} |
| 90 | +``` |
0 commit comments