|
| 1 | +# Bypassing MFA within OCI IAM for Service Accounts |
| 2 | + |
| 3 | +Owner: Paul Toal |
| 4 | + |
| 5 | +During authentication, it is widely recognised that Multi-Factor Authentication (MFA) should be used to increase the security of a user's credential and reduce the chance of a brute force attack. However, there are certain use cases where it may be necessary to disable MFA for a particular account. |
| 6 | + |
| 7 | +One common use case is when using an OCI IAM account as a service account to call IAM protected endpoints. For example, Oracle Integration Cloud (OIC) allows users to build integrations and expose them as REST endpoints (amongst other things). When calling that REST endpoint, either BASIC or OAUTH authentication can be used to authenticate the requestor to the REST API. |
| 8 | + |
| 9 | +Whilst the recommended approach is to always use OAUTH authentication, there are situations where this can't be used and BASIC authentication must be used instead. If MFA is enabled on that user account, then BASIC authentication cannot be used as the REST endpoint returns a 401 Unauthorised status code. |
| 10 | + |
| 11 | +This tutorial will show you how to configure OCI IAM sign-on policies to bypass MFA for specific accounts accessing specific resources/applications. The use case is to enable a client (which only supports BASIC authentication) to call a deployed integrations REST endpoint on OIC. |
| 12 | + |
| 13 | +> ***Note*** MFA should only be disabled for specific users and for specific use cases, such as the one described above. As best practice, MFA should be enabled and enforced for all users. |
| 14 | +
|
| 15 | +## Prerequisites |
| 16 | + |
| 17 | + - An OCI tenancy. |
| 18 | + - An OCI Administrator with appropriate permissions manage your IAM Identity Domain. |
| 19 | + - An OIC instance. |
| 20 | + - A sample integration with a REST endpoint deployed within OIC. |
| 21 | + - A test user within IAM with an appropriate OIC app role to call the integration endpoint. |
| 22 | + |
| 23 | +# Testing User Authentication |
| 24 | + |
| 25 | +This use case assumes that there is a sign-on policy configured within OCI IAM that enforces MFA for your users (including your test user) and therefore your users get challenged for MFA when they access OIC. |
| 26 | + |
| 27 | +Let's first test this by logging into the OIC service console as our test user (Marty McFly)... |
| 28 | + |
| 29 | +  |
| 30 | + |
| 31 | +Now that we know MFA is being enforced for our test user, we can show that we are unable to call an OIC integration endpoint using basic authentication. The screenshot below show the 401 Unauthorised status code being returned by Postman. |
| 32 | + |
| 33 | +  |
| 34 | + |
| 35 | + # Amending the Sign-On Policy |
| 36 | + |
| 37 | +To allow the service account to be able to call the REST API, changes need to be made to the OCI IAM sign-on policy so that MFA can be bypassed for the service account (marty.mcfly) when accessing the OIC application. |
| 38 | + |
| 39 | +> ***Note*** The aim is not to disable MFA for the service account for all applications as that introduces unnecessary risk. Therefore, MFA will only be disabled for the service account for the OIC application. |
| 40 | +
|
| 41 | +In this example, MFA for OIC is being enforced by its own sign-on policy. It may be the case that the Default Sign-On policy has been amended to force MFA for all users and all applications by default. If this is the case, then, the recommendation would still be to create an application-specific sign-on policy, just for OIC (or whatever your target application is). |
| 42 | + |
| 43 | +Looking at the current list of sign-on policies, there are two out-of-the-box policies and the additional OIC policy. |
| 44 | + |
| 45 | +  |
| 46 | + |
| 47 | +Editing the OIC policy and looking at the rule within it, we can see that it has no conditions current set. |
| 48 | + |
| 49 | +  |
| 50 | + |
| 51 | +We can also see that the actions are enforcing MFA. |
| 52 | + |
| 53 | +  |
| 54 | + |
| 55 | +Finally, we can see that the sign-on policy is attached to the OIC application. |
| 56 | + |
| 57 | +  |
| 58 | + |
| 59 | +Based on the above policy, all users accessing OIC will be challenged for MFA everytime they authenticate. |
| 60 | + |
| 61 | +However, we need to exclude our service account from MFA. Since your number of service accounts that fall into this use case will typically be a small number, the easiest way of doing this is to add your list of service accounts to the "Exclude Users" condition, i.e., |
| 62 | + |
| 63 | +  |
| 64 | + |
| 65 | +Save those changes and that's it! |
| 66 | + |
| 67 | + # Testing the API call |
| 68 | + |
| 69 | +The final step is to test the API call again. |
| 70 | + |
| 71 | +  |
| 72 | + |
| 73 | +We can see that our API call is now successful for our service account and it is able to obtain a response. |
| 74 | + |
| 75 | + # Other Considerations |
| 76 | + |
| 77 | +The example above shows how easy it is to exclude service accounts from MFA in order to enable this use case. This approach is fine on a small scale, where you only have one or two service accounts. It may be the case that you have many service accounts, or that they are being managed by an external identity service and provisioned into OCI IAM. For example, you might have a group containing all of the OIC service accounts that is populated and managed by an external service. In this situation, since the sign-on policy conditions can only exclude individual users (not groups), you can't take quite the same approach. |
| 78 | + |
| 79 | +The above approach is also only appropriate when you have an application-specific sign-on policy enforcing MFA. If the Default Sign-On Policy has been amended so that MFA is being enforced for all users against all applications, then just exluding the user in an app specific policy won't work, as the Default policy will then apply and the user will still be challenged for MFA. |
| 80 | + |
| 81 | +However, the good news is that you can still meet your use case in either of the above cases. The approach needed is slightly different. In these circumstances we build our application-specific sign-on policy slightly differently. |
| 82 | + |
| 83 | +Let's build a sign-on policy where the service accounts are contained in a group. |
| 84 | + |
| 85 | +> ***Note*** The sign-on policy has been reverted back to its original state, i.e., removed Marty McFly from the Excluded Users so that MFA is enforced for all users accessing OIC, including Marty. |
| 86 | +
|
| 87 | + |
| 88 | + |
| 89 | +As you can see, I now have created a group containing the service account(s). |
| 90 | + |
| 91 | +Within the sign-on policy, add a new rule (in addition to the existing rule enforcing MFA). This rule will allow any user in the `OIC Service Accounts` group to access OIC, but the actions won't force an additional factor. |
| 92 | + |
| 93 | +Adding a new rule to the existing `Sign-On Policy for OIC`, within the conditions, I add my service accounts group. |
| 94 | + |
| 95 | + |
| 96 | + |
| 97 | +The actions allow access without the additional factor. |
| 98 | + |
| 99 | + |
| 100 | + |
| 101 | +Lastly, the rules within the sign-on policy need to be reordered so that the more specific rule containing the group condition is executed first. This is done using the `Edit Priority` button on the list of rules. |
| 102 | + |
| 103 | + |
| 104 | + |
| 105 | +That's it! I can re-test the API call and it is still successful using this alternative approach. |
| 106 | + |
| 107 | +# Summary |
| 108 | + |
| 109 | +In this tutorial, I have explained how you can configure IAM to bypass MFA for service accounts. |
| 110 | + |
| 111 | +As stated at the top of this tutorial, OAUTH is the preferred mechanism for authenticating to REST APIs. However, for situations where that isn't possible and BASIC authentication must be used, hopefully this tutorial will help you to achieve this. |
| 112 | + |
| 113 | +# License |
| 114 | + |
| 115 | +Copyright (c) 2025 Oracle and/or its affiliates. |
| 116 | + |
| 117 | +Licensed under the Universal Permissive License (UPL), Version 1.0. |
| 118 | + |
| 119 | +See [LICENSE](https://github.com/oracle-devrel/technology-engineering/blob/main/LICENSE) for more details. |
0 commit comments