## Class security_context

zeep::http::security_context — class that manages security in a HTTP scope

## Synopsis

    // In header: <zeep/http/security.hpp>

    class security_context {
    public:
      // member classes/structs/unions

      struct rule {

        // public data members
        std::string m_pattern;
        std::set< std::string > m_roles;
      };
      // construct/copy/destruct
      security_context(const std::string &, user_service &, bool = false);
      security_context(const security_context &) = delete;
      security_context & operator=(const security_context &) = delete;

      // public member functions
      template<typename PWEncoder> void register_password_encoder();
      void add_rule(const std::string &, const std::string &);
      void add_rule(std::string, std::initializer_list< std::string >);
      void validate_request(request &) const;
      void add_authorization_headers(reply &, const std::string &);
      void add_authorization_headers(reply &, const user_details);
      void verify_username_password(const std::string &, const std::string &,
                                    reply &);
      user_service & get_user_service() const;
      std::pair< std::string, bool > get_csrf_token(request &);
      void set_validate_csrf(bool);
      bool get_validate_csrf() const;
    };

## Description

Add this to a HTTP server and it will check authentication. Access to certain paths can be limited by specifying which 'roles' are allowed.

The authentication mechanism used is based on JSON Web Tokens, JWT in short.

### `security_context` public construct/copy/destruct

1.     security_context(const std::string & secret, user_service & users,
                        bool defaultAccessAllowed = false);

   constructor taking a validator

   Create a security context for server s with validator validator and a flag defaultAccessAllowed indicating if non-matched uri's should be allowed

2.     security_context(const security_context &) = delete;

3.     security_context & operator=(const security_context &) = delete;

### `security_context` public member functions

1.     template<typename PWEncoder> void register_password_encoder();

   register a custom password encoder

   The password encoder should derive from the abstract password encoder class above and also implement the name() method.

2.     void add_rule(const std::string & glob_pattern, const std::string & role);

   Add a new rule for access.

   A new rule will be added to the list, allowing access to glob_pattern to users having role role

   glob_pattern should start with a slash

3.     void add_rule(std::string glob_pattern,
                     std::initializer_list< std::string > roles);

   Add a new rule for access.

   A new rule will be added to the list, allowing access to glob_pattern to users having a role in roles

   If roles is empty, access is allowed to anyone.

   glob_pattern should start with a slash

4.     void validate_request(request & req) const;

   Validate the request req against the stored rules.

   This method will validate the request in req agains the stored rules and will throw an exception if access is not allowed. The request req will be updated with the credentials for further use. If the validate CSRF is set, the CSRF token will also be validated.

5.     void add_authorization_headers(reply & rep, const std::string & username);

   Add e.g. headers to reply for an authorized request.

   When validation succeeds, a HTTP reply is send to the user and this routine will be called to augment the reply with additional information.

   Parameters:

   `rep` | Then `zeep::http::reply` object that will be send to the user
   `username` | The name for the authorized user, credentials will be fetched from the `user_service`

6.     void add_authorization_headers(reply & rep, const user_details user);

   Add e.g. headers to reply for an authorized request.

   When validation succeeds, a HTTP reply is send to the user and this routine will be called to augment the reply with additional information.

   Parameters:

   `rep` | Then `zeep::http::reply` object that will be send to the user
   `user` | The authorized user details

7.     void verify_username_password(const std::string & username,
                                     const std::string & password, reply & rep);

   verify the username/password combination and set a cookie in the reply in case of success

   When validation succeeds, add_authorization_headers is called, otherwise an exception is thrown.

   Parameters:

   `password` | The password for the user
   `rep` | Then `zeep::http::reply` object that will be send back to the browser
   `username` | The name for the user

8.     user_service & get_user_service() const;

   return reference to the `user_service` object

9.     std::pair< std::string, bool > get_csrf_token(request & req);

   Get or create a CSRF token for the current request.

   Return a CSRF token. If this was not present in the request, a new will be generated

   Parameters:

   `req` | The HTTP request

   Returns: | A std::pair containing the CSRF token and a flag indicating the token is new

10.     void set_validate_csrf(bool validate);

    To automatically validate CSRF tokens, set this flag.

11.     bool get_validate_csrf() const;