You are here

Home » API reference » SAML Authentication 8.2

README.txt in SAML Authentication 8.2

Same filename and directory in other branches
  1. 7 README.txt
CONTENTS OF THIS FILE
---------------------
 * Introduction
 * Requirements
 * Installation
 * Configuration

INTRODUCTION
------------
This module allows users to authenticate against a SAML identity provider
to login to your Drupal site. After adding the configuration your Drupal site
can be used as a SAML service provider.

Read more about SAML on wikipedia: https://en.wikipedia.org/wiki/SAML_2.0

REQUIREMENTS
------------
This module depends on OneLogin's SAML PHP Toolkit:
https://github.com/onelogin/php-saml

DEMO
------------
Watch a detailed explanation on how to use this module (v1) in the video
tutorial: https://www.youtube.com/watch?v=7XCp0SvFoPQ

INSTALLATION
------------
Install as you would normally install a contributed drupal module. See:
https://www.drupal.org/documentation/install/modules-themes/modules-8
for further information.

CONFIGURATION
-------------
Create a public/private key pair to use Drupal as a service provider.
openssl req -new -x509 -days 3652 -nodes -out sp.crt -keyout sp.key

Go to /admin/config/people/saml to configure the module.

Service Provider Configuration:
Entity ID:        [choose a unique name]
Name ID:          urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
x509 Certificate: [the generated public key]
Private Key:      [the generated private key]

Your cert/key pair can be set in the admin screen, or kept on disk - in which
case you need to enter only the path. (The SAML Toolkit puts some restrictions
on the directory name, though.)

Ask for the metadata XML from the identity provider. Retrieve the needed
settings below from the metadata XML.

Identity Provider Configuration:
- Entity ID
- Single Sign On Service
- Single Log Out Service
- Change Password Service
- x509 Certificate

Supply the generated metadata XML to identity provider to get the service
provider added. Everything the identity provider needs is in the metadata XML.
  /saml/metadata

Add permissions for metadata XML to the anonymous user if it should be
anonymously accessible to the identity provider.

This should be enough to do a basic login. Configure the module to create new
users if needed or allow it to map existing users. The specific configuration
depends on the attributes delivered by the identity provider.

DEBUGGING
---------
You can use third party tools to help debug your SSO flow with SAML. The
following are browser extensions that can be used on Linux, macOS and Windows:

Google Chrome:
- SAML Chrome Panel: https://chrome.google.com/webstore/detail/saml-chrome-panel/paijfdbeoenhembfhkhllainmocckace

FireFox:
- SAML Tracer: https://addons.mozilla.org/en-US/firefox/addon/saml-tracer/

These tools will allow you to see the SAML request/response and the method
(GET, POST or Artifact) the serialized document is sent/received.

If you are configuring a new SAML connection it is wise to first test without
encryption enabled and then enable encryption once a non encrypted assertion
is successful.

The listed third party tools do not decrypt SAML assertions, but you can use
OneLogin's Decrypt XML tool at https://www.samltool.com/decrypt.php.

You can also find more debugging tools located at
https://www.samltool.com/saml_tools.php.

File

README.txt
View source 
  1. CONTENTS OF THIS FILE

  2. ---------------------

  3.  * Introduction

  4.  * Requirements

  5.  * Installation

  6.  * Configuration

  7. 

  8. INTRODUCTION

  9. ------------

  10. This module allows users to authenticate against a SAML identity provider

  11. to login to your Drupal site. After adding the configuration your Drupal site

  12. can be used as a SAML service provider.

  13. 

  14. Read more about SAML on wikipedia: https://en.wikipedia.org/wiki/SAML_2.0

  15. 

  16. REQUIREMENTS

  17. ------------

  18. This module depends on OneLogin's SAML PHP Toolkit:

  19. https://github.com/onelogin/php-saml

  20. 

  21. DEMO

  22. ------------

  23. Watch a detailed explanation on how to use this module (v1) in the video

  24. tutorial: https://www.youtube.com/watch?v=7XCp0SvFoPQ

  25. 

  26. INSTALLATION

  27. ------------

  28. Install as you would normally install a contributed drupal module. See:

  29. https://www.drupal.org/documentation/install/modules-themes/modules-8

  30. for further information.

  31. 

  32. CONFIGURATION

  33. -------------

  34. Create a public/private key pair to use Drupal as a service provider.

  35. openssl req -new -x509 -days 3652 -nodes -out sp.crt -keyout sp.key

  36. 

  37. Go to /admin/config/people/saml to configure the module.

  38. 

  39. Service Provider Configuration:

  40. Entity ID:        [choose a unique name]

  41. Name ID:          urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified

  42. x509 Certificate: [the generated public key]

  43. Private Key:      [the generated private key]

  44. 

  45. Your cert/key pair can be set in the admin screen, or kept on disk - in which

  46. case you need to enter only the path. (The SAML Toolkit puts some restrictions

  47. on the directory name, though.)

  48. 

  49. Ask for the metadata XML from the identity provider. Retrieve the needed

  50. settings below from the metadata XML.

  51. 

  52. Identity Provider Configuration:

  53. - Entity ID

  54. - Single Sign On Service

  55. - Single Log Out Service

  56. - Change Password Service

  57. - x509 Certificate

  58. 

  59. Supply the generated metadata XML to identity provider to get the service

  60. provider added. Everything the identity provider needs is in the metadata XML.

  61.   /saml/metadata

  62. 

  63. Add permissions for metadata XML to the anonymous user if it should be

  64. anonymously accessible to the identity provider.

  65. 

  66. This should be enough to do a basic login. Configure the module to create new

  67. users if needed or allow it to map existing users. The specific configuration

  68. depends on the attributes delivered by the identity provider.

  69. 

  70. DEBUGGING

  71. ---------

  72. You can use third party tools to help debug your SSO flow with SAML. The

  73. following are browser extensions that can be used on Linux, macOS and Windows:

  74. 

  75. Google Chrome:

  76. - SAML Chrome Panel: https://chrome.google.com/webstore/detail/saml-chrome-panel/paijfdbeoenhembfhkhllainmocckace

  77. 

  78. FireFox:

  79. - SAML Tracer: https://addons.mozilla.org/en-US/firefox/addon/saml-tracer/

  80. 

  81. These tools will allow you to see the SAML request/response and the method

  82. (GET, POST or Artifact) the serialized document is sent/received.

  83. 

  84. If you are configuring a new SAML connection it is wise to first test without

  85. encryption enabled and then enable encryption once a non encrypted assertion

  86. is successful.

  87. 

  88. The listed third party tools do not decrypt SAML assertions, but you can use

  89. OneLogin's Decrypt XML tool at https://www.samltool.com/decrypt.php.

  90. 

  91. You can also find more debugging tools located at

  92. https://www.samltool.com/saml_tools.php.