{"_id":"5638d6c12fc5520d001a4cc9","category":{"_id":"54343531bfaa3d0800c4d4b0","pages":["54349c225b10711400c6c539","54349c905b10711400c6c53b","54370bea4e799808006da391","54370fa726469424002a6e19","5480aad4e952bb1a006b320c","5638d6c12fc5520d001a4cc9","568fe01b21fcf0190071d8fb"],"project":"54343170fa5527080064f449","version":"54343531bfaa3d0800c4d4af","__v":8,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2014-10-07T18:31:12.137Z","from_sync":false,"order":0,"slug":"documentation","title":"Documentation"},"__v":11,"project":"54343170fa5527080064f449","user":"54bd5e07b336d20c00dbd211","version":{"_id":"54343531bfaa3d0800c4d4af","project":"54343170fa5527080064f449","__v":27,"forked_from":"54343170fa5527080064f44c","createdAt":"2014-10-07T18:47:13.086Z","releaseDate":"2014-10-07T18:47:13.086Z","categories":["54343531bfaa3d0800c4d4b0","543435b1edce040800409240","543435b9edce040800409241","543435bcedce040800409243","543435bfedce040800409244","543435c2edce040800409245","54370cc426469424002a6dfa","54370cf026469424002a6dfd","5437129d26469424002a6e2f","543712d226469424002a6e30","5480c8fd74904f1a00053c86","54aafc6eefb39016009e4d71","54ac1d36de18cc1400226e01","54ad59369219922100751732","54b41bcf4f25cb1600518d2c","54b533a3a806f40c0050d53c","54b54bbf96fe3c0b00d38d2a","54b688a27379a90c00f53a8a","54b699efbc1a46160005edfa","54b8191691011f0b00068804","54bfb002d03bfc0d0000e814","54bfb33ed03bfc0d0000e816","55a3e94e912a6e2300882cdb","55a56c370f354f0d00fd02a8","55e85ad034516037002e9325","5638ecb62fc5520d001a4cf9","572cba2fc310640e008f63d5"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"3.0.0","version":"3.0"},"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-11-03T15:46:09.615Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":6,"body":"For increased security MediaSilo recommends that users configure multi-factor authentication (MFA); which adds an additional layer of security by requiring users to enter a unique security code from an approved device.\n\nMFA must be configured on a per user basis and must be setup by the user.  MFA can not be setup for a user by a third party.  An admin on the same account can remove MFA for a user if the authentication device is lost or damaged.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"How to Configure MFA\"\n}\n[/block]\nEnabling MFA for a user is a two step process, once enabled the user will be required to enter the security code every time they authenticate with the MediaSilo platform.\n\nBefore the setup the user will need an MFA device that supports the [TOTP algorithm](https://tools.ietf.org/html/rfc6238); the Google Authenticator is a great option that supports this algorithm and is available on most devices.\n\n**Generate MFA Key**\nYou first need to generate a key that will be used to generate the security code, to do this you will need to make an authenticated request to the MediaSilo API with the user that wants to enable MFA.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"POST /v3/mfa/key\",\n      \"language\": \"http\"\n    }\n  ]\n}\n[/block]\nThis request will return the following JSON object:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"key\\\": \\\"HMFXTL6CM4GZBCP6\\\",\\n    \\\"qrUrl\\\": \\\"https://chart.googleapis.com/chart?chs=200x200&chld=M%7C0&cht=qr&chl=otpauth%3A%2F%2Ftotp%2FMediaSilo%3Asimonlamprell%3Fsecret%3DHMFXTL6CM4GZBCP6%26issuer%3DMediaSilo\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nThe field labeled 'key' contains the MFA security key needed to setup the MFA device.  The JSON object also contains a field 'qrUrl' which is a link to a scan-able QR code which can also be used to setup the MFA device.\n\nOnce the device is configured to use this key, you have to complete the MFA setup by sending a device generated code to the MediaSilo API.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"POST /v3/mfa\\n{\\n  \\\"code\\\":\\\"123456\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nAfter this request completes successfully MFA will be enabled for this user.  The following authenticated request will remove MFA from a users account:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"DELETE /v3/mfa\",\n      \"language\": \"http\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Authentication with MFA\"\n}\n[/block]\nEnabling MFA changes how a user is authenticated when making requests to the MediaSilo API.  Basic Auth is supported but not recommended because the security code changes every minute which would require the user to re-enter the security code.  This would be a bad user experience, which is why we suggest using sessions.  With sessions the security code is only required when creating the session, after that authorization is done with the session which allows for a more consistent user experience.\n\n**Session Authentication**\nThe process of authenticating with a session remains unchanged by MFA except when you create the session.  Creating the session happens as it did before except it now requires the field \"code\" as well as the usual \"username\", \"password\", and \"hostname\".  If you try to create a session for a user with MFA enabled with out passing the security code, the session creation will fail with the error \"This user has MFA enabled but no code was provided.\"\n\n**Basic Authentication**\nUsing this method a new header will be required for users with MFA enabled.  Any user with MFA enabled that does not provide this new header with a valid security code will receive a 403 Unauthorized response.  The new header required is \"MediaSiloMfaCode\" whose value must be a valid security code from the MFA device.\n\nThe security code is a time based code, which means it is only valid for a certain amount of time.  When the security code expires a new one will need to be generated and passed along in this header.","excerpt":"","slug":"multi-factor-authentication","type":"basic","title":"Multi-Factor Authentication"}

Multi-Factor Authentication


For increased security MediaSilo recommends that users configure multi-factor authentication (MFA); which adds an additional layer of security by requiring users to enter a unique security code from an approved device. MFA must be configured on a per user basis and must be setup by the user. MFA can not be setup for a user by a third party. An admin on the same account can remove MFA for a user if the authentication device is lost or damaged. [block:api-header] { "type": "basic", "title": "How to Configure MFA" } [/block] Enabling MFA for a user is a two step process, once enabled the user will be required to enter the security code every time they authenticate with the MediaSilo platform. Before the setup the user will need an MFA device that supports the [TOTP algorithm](https://tools.ietf.org/html/rfc6238); the Google Authenticator is a great option that supports this algorithm and is available on most devices. **Generate MFA Key** You first need to generate a key that will be used to generate the security code, to do this you will need to make an authenticated request to the MediaSilo API with the user that wants to enable MFA. [block:code] { "codes": [ { "code": "POST /v3/mfa/key", "language": "http" } ] } [/block] This request will return the following JSON object: [block:code] { "codes": [ { "code": "{\n \"key\": \"HMFXTL6CM4GZBCP6\",\n \"qrUrl\": \"https://chart.googleapis.com/chart?chs=200x200&chld=M%7C0&cht=qr&chl=otpauth%3A%2F%2Ftotp%2FMediaSilo%3Asimonlamprell%3Fsecret%3DHMFXTL6CM4GZBCP6%26issuer%3DMediaSilo\"\n}", "language": "json" } ] } [/block] The field labeled 'key' contains the MFA security key needed to setup the MFA device. The JSON object also contains a field 'qrUrl' which is a link to a scan-able QR code which can also be used to setup the MFA device. Once the device is configured to use this key, you have to complete the MFA setup by sending a device generated code to the MediaSilo API. [block:code] { "codes": [ { "code": "POST /v3/mfa\n{\n \"code\":\"123456\"\n}", "language": "json" } ] } [/block] After this request completes successfully MFA will be enabled for this user. The following authenticated request will remove MFA from a users account: [block:code] { "codes": [ { "code": "DELETE /v3/mfa", "language": "http" } ] } [/block] [block:api-header] { "type": "basic", "title": "Authentication with MFA" } [/block] Enabling MFA changes how a user is authenticated when making requests to the MediaSilo API. Basic Auth is supported but not recommended because the security code changes every minute which would require the user to re-enter the security code. This would be a bad user experience, which is why we suggest using sessions. With sessions the security code is only required when creating the session, after that authorization is done with the session which allows for a more consistent user experience. **Session Authentication** The process of authenticating with a session remains unchanged by MFA except when you create the session. Creating the session happens as it did before except it now requires the field "code" as well as the usual "username", "password", and "hostname". If you try to create a session for a user with MFA enabled with out passing the security code, the session creation will fail with the error "This user has MFA enabled but no code was provided." **Basic Authentication** Using this method a new header will be required for users with MFA enabled. Any user with MFA enabled that does not provide this new header with a valid security code will receive a 403 Unauthorized response. The new header required is "MediaSiloMfaCode" whose value must be a valid security code from the MFA device. The security code is a time based code, which means it is only valid for a certain amount of time. When the security code expires a new one will need to be generated and passed along in this header.