How to Securely Store Secrets in Dynamics 365 Business Ce...

What is the best way to save secrets in AL?

When developing integrations or extensions for Microsoft Business Central, it is often necessary to store sensitive data such as:

API keys
OAuth tokens
client secrets
integration credentials

A common mistake is storing such values directly in tables or configuration fields. Even features like field masking do not actually secure the underlying data.

In my previous post I explained why field masking is not a reliable way to store secrets in Business Central. If you haven’t read it yet, you can find it here: Does Field Masking Protect Secrets?

In this post, I will show the recommended way to store secrets in AL without using external services such as Azure Key Vault.

What Is Isolated Storage?

Isolated Storage is a built-in data storage mechanism that keeps separation between extensions, isolating keys and values between extensions.

Isolated Storage can be accessed through a dedicated IsolatedStorage data type. The storage uses the DataScope option to determine the visibility of stored values.

Technically Isolated Storage is implemented as a separate table with property: DataPerCompany = false This means that the storage exists once per environment rather than per company.

The table cannot to be accessed directly in SaaS environments. Developers should use IsolatedStorage data type.

Isolated Storage Table Structure

App ID: Guid PK
Scope: Option PK
Company Name: Text[30] PK
User ID: Guid PK
Key: Text[250] PK
Value: BLOB
Encryption Status: Option
Target Value Type: SecretText

The actual value is stored in a BLOB field, which allows secure handling of the data.

Understanding DataScope

DataScope determines who can access the stored secret.

Depending on the scope, different fields are populated when the record is created.

Scope	Description
Module	Secret available only within the extension
Company	Secret available for a specific company
User	Secret available for a specific user
CompanyAndUser	Secret available only for a specific user in a specific company

When a value is stored, Business Central automatically fills the relevant fields:

Module → only App ID Company → Company Name User → User ID CompanyAndUser → both Company Name and User ID

This design ensures that secrets are properly isolated and scoped.

Supported methods

The IsolatedStorage library provides several methods for working with stored values:

Get

Retrieves the value from Isolated Storage table based on:

key
DataScope In SaaS environments, the method supports both:
Text
SecretText

Set

Stores a value in Isolated Storage using specified key and DataScope. If the key does not exist yet, a new record is created.

SetEncrypted

Stores and encryps a value before saving it.

Table input value cannot exceed 215 characters..

Contains

Checks whether a value exists for the given key and DataScope.

Delete

Removes the record associated with the given key and DataScope.

Example Implementation

To demonstrate how Isolated Storage works with different scopes, I created a custom table for managing secrets. The table allows users to define:

a secret key
a value
the desired DataScope

Secrets

Since AL does not allow using the DataScope option directly as a table field, I introduced a separate enum called Data Scope. A mapping function named MapToDataScope converts the enum value to the appropriate DataScope option.

DataScope_Field

The page includes two actions:

Get Secret

Returns a SecretText value for the specified Key and DataScope. DataScope_Field

Set Secret

Stores a secret using a given key and scope. DataScope_Field

If you prefer not to use an action to set the secret, you can add a variable as a page field and call the Get method during field validation.

Code

1
enum 50400 "Data Scope"
2
{
3
    Extensible = true;
4

5
    value(0; "Company")
6
    {
7
        Caption = 'Company';
8
    }
9
    value(1; "CompanyAndUser")
10
    {
11
        Caption = 'Company And User';
12
    }
13
    value(2; "User")
14
    {
15
        Caption = 'User';
16
    }
17
    value(3; "Module")
18
    {
19
        Caption = 'Module';
20
    }
21
}
22
table 50400 Secret
23
{
24
    Caption = 'Secret';
25

26
    fields
27
    {
28
        field(1; "Code"; Code[20])
29
        {
30
            Caption = 'Code';
31
        }
32
        field(2; Description; Text[250])
33
        {
34
            Caption = 'Description';
35
        }
36
        field(3; "Data Scope"; Enum "Data Scope")
37
        {
38
            Caption = 'Data Scope';
39
        }
40
        field(4; "Secret ID"; Guid)
41
        {
42
            Caption = 'Secret ID';
43
            Editable = false;
44
        }
45
    }
46
    keys
47
    {
48
        key(PK; "Code")
49
        {
50
            Clustered = true;
51
        }
52
    }
53

54

55
    trigger OnDelete()
56
    var
57
        IsolatedStorageImpl: Codeunit "Isolated Storage Impl.";
58
    begin
59
        IsolatedStorageImpl.Delete(Rec."Secret ID", Rec.MapToDataScope(Rec."Data Scope"));
60
    end;
61

62
    procedure MapToDataScope(SecretDataScope: Enum "Data Scope"): DataScope
63
    begin
64
        case SecretDataScope of
65
            SecretDataScope::Company:
66
                exit(DataScope::Company);
67
            SecretDataScope::"CompanyAndUser":
68
                exit(DataScope::CompanyAndUser);
69
            SecretDataScope::Module:
70
                exit(DataScope::Module);
71
            SecretDataScope::User:
72
                exit(DataScope::User);
73
        end;
74
    end;
75
}

The following codeunit contains all methods needed to manage Isolated Storage:

Get Returns SecretText (it can be overloaded to return Text if needed) for given Key and DataScope.
Set Creates new secret key if the provided key is empty. The value is stored using the specified or newly generated Key and DataScope. If encryption is enabled in the environment, the method automatically uses SetEncrypted instead of Set.
Delete Removes a secret associated with the specified Key and DataScope. Before deleting, the method verifies that the record exists in Isolated Storage.

1
interface "Isolated Storage"
2
{
3
    procedure Set(var IsolatedKey: Guid; SecretText: SecretText; Scope: DataScope);
4
    procedure Get(IsolatedKey: Guid; Scope: DataScope): SecretText;
5
    procedure Delete(IsolatedKey: Guid; Scope: DataScope): Boolean;
6
}
7

8
codeunit 50400 "Isolated Storage Impl." implements "Isolated Storage"
9
{
10
    [NonDebuggable]
11
    procedure Set(var IsolatedKey: Guid; SecretText: SecretText; Scope: DataScope)
12
    begin
13
        if IsNullGuid(IsolatedKey) then
14
            IsolatedKey := CreateGuid();
15

16
        if EncryptionEnabled() then
17
            IsolatedStorage.SetEncrypted(IsolatedKey, SecretText, Scope)
18
        else
19
            IsolatedStorage.Set(IsolatedKey, SecretText, Scope);
20
    end;
21

22
    [NonDebuggable]
23
    procedure Get(IsolatedKey: Guid; Scope: DataScope) SecretText: SecretText
24
    begin
25
        if IsolatedStorage.Contains(IsolatedKey, Scope) and not IsNullGuid(IsolatedKey) then
26
            IsolatedStorage.Get(IsolatedKey, Scope, SecretText);
27
    end;
28

29
    [NonDebuggable]
30
    procedure Delete(IsolatedKey: Guid; Scope: DataScope): Boolean
31
    begin
32
        if not IsolatedStorage.Contains(IsolatedKey, Scope) then
33
            exit;
34

35
        IsolatedStorage.Delete(IsolatedKey, Scope);
36
    end;
37
}
38

39
page 50400 "Secrets"
40
{
41
    ApplicationArea = All;
42
    Caption = 'Secrets';
43
    InsertAllowed = false;
44
    PageType = List;
45
    SourceTable = "Secret";
46
    UsageCategory = Administration;
47

48
    layout
49
    {
50
        area(Content)
51
        {
52
            repeater(General)
53
            {
54
                field(Code; Rec.Code)
55
                {
56
                    Editable = false;
57
                    ToolTip = 'Specifies the value of the Code field.';
58
                }
59
                field(Description; Rec.Description)
60
                {
61
                    ToolTip = 'Specifies the value of the Description field.';
62
                }
63
                field("Data Scope"; Rec."Data Scope")
64
                {
65
                    Editable = false;
66
                    ToolTip = 'Specifies the value of the Data Scope field.';
67
                }
68
            }
69
        }
70
    }
71
    actions
72
    {
73

74
        area(Processing)
75
        {
76
            action("Set Secret")
77
            {
78
                ApplicationArea = all;
79
                Caption = 'Set Secret';
80
                Promoted = true;
81
                PromotedCategory = Process;
82
                ToolTip = 'Allows to set a new secret.';
83
                trigger OnAction()
84
                begin
85
                    this.SetSecret();
86
                end;
87
            }
88

89
            action("Get Secret")
90
            {
91
                ApplicationArea = all;
92
                Caption = 'Get Secret';
93
                Promoted = true;
94
                PromotedCategory = Process;
95
                ToolTip = 'Allows to get a secret.';
96
                trigger OnAction()
97
                var
98
                    SecretText: SecretText;
99
                begin
100
                    SecretText := this.IsolatedStorageImpl.Get(Rec."Secret ID", Rec.MapToDataScope(Rec."Data Scope"));
101
                    // Target = OnPrem only
102
                    Message(SecretText.Unwrap());
103
                end;
104
            }
105
        }
106
    }
107

108
    local procedure SetSecret()
109
    var
110
        NewSecret: Record Secret;
111
        SecretDialog: Page "Set Secret Dialog";
112
        SecretText: SecretText;
113
    begin
114
        if SecretDialog.RunModal() = Action::OK then begin
115
            SecretDialog.SetSecret(NewSecret);
116
            SecretText := SecretDialog.GetSecret();
117

118
            this.IsolatedStorageImpl.Set(NewSecret."Secret ID", SecretText, NewSecret.MapToDataScope(NewSecret."Data Scope"));
119
            NewSecret.Modify(true);
120

121
            Commit();
122
        end;
123
    end;
124

125
    var
126
        IsolatedStorageImpl: Codeunit "Isolated Storage Impl.";
127
}
128
page 50401 "Set Secret Dialog"
129
{
130
    ApplicationArea = All;
131
    Caption = 'Set Secret';
132
    PageType = StandardDialog;
133

134
    layout
135
    {
136
        area(Content)
137
        {
138
            field(Code; this.Code)
139
            {
140
                Caption = 'Code';
141
                ToolTip = 'Specifies the value of the Code field.';
142
            }
143
            field(Description; this.Description)
144
            {
145
                Caption = 'Description';
146
                ToolTip = 'Specifies the value of the Description field.';
147
            }
148
            field("Data Scope"; this.DataScope)
149
            {
150
                Caption = 'Data Scope';
151
                ToolTip = 'Specifies the value of the Data Scope field.';
152
            }
153
            field("Secret Text"; this.SecretText)
154
            {
155
                Caption = 'Secret Text';
156
                MaskType = Concealed;
157
                ToolTip = 'Specifies the value of the Secret Text field.';
158
            }
159
        }
160
    }
161

162
    procedure SetSecret(var Secret: Record Secret)
163
    begin
164
        Secret.Init();
165
        Secret.Code := this.Code;
166
        Secret.Description := this.Description;
167
        Secret."Data Scope" := this.DataScope;
168
        Secret.Insert(true);
169
    end;
170

171
    procedure GetSecret(): Text[250]
172
    begin
173
        exit(this.SecretText);
174
    end;
175

176
    var
177
        Code: Code[20];
178
        Description: Text[250];
179
        DataScope: Enum "Data Scope";
180

181
        [NonDebuggable]
182
        SecretText: Text[250];
183
}

Working with Isolated Storage in On-Premises Environments

In On-Prem environments, developers have the option to declare the Isolated Storage table directly as a record variable.

This provides additional access to internal fields such as:

Target Value Type
Encryption Status

The SecretText data type cannot be used directly in this scenario, because there is no overload of OutStream.WriteText that supports SecretText.

For this reason, using the global IsolatedStorage variable is generally the recommended approach. Direct table access should only be used in very specific scenarios.

1
codeunit 50403 "Isolated Storage - OnPremOnly"
2
{
3

4
    procedure Set(Secret: Record Secret; Value: Text)
5
    var
6
        IsolatedStorageRecord: Record "Isolated Storage";
7
        ModuleInfo: ModuleInfo;
8
        OutStreamValue: OutStream;
9
    begin
10
        NavApp.GetCurrentModuleInfo(ModuleInfo);
11
        IsolatedStorageRecord.Init();
12
        IsolatedStorageRecord."App Id" := ModuleInfo.Id;
13
        IsolatedStorageRecord.Scope := DataScopeToOption(Secret."Data Scope");
14
        IsolatedStorageRecord."Company Name" := CopyStr(CompanyName(), 1, 30);
15
        IsolatedStorageRecord."User Id" := UserSecurityId();
16
        IsolatedStorageRecord."Key" := Secret."Secret ID";
17
        IsolatedStorageRecord.Value.CreateOutStream(OutStreamValue);
18
        OutStreamValue.WriteText(Value);
19
        IsolatedStorageRecord.Insert(true);
20
    end;
21

22
    procedure Get(SecretID: Guid; Scope: DataScope) ValueText: Text
23
    var
24
        IsolatedStorageRecord: Record "Isolated Storage";
25
        ModuleInfo: ModuleInfo;
26
        ValueInStream: InStream;
27
    begin
28
        NavApp.GetCurrentModuleInfo(ModuleInfo);
29
        if IsolatedStorageRecord.Get(ModuleInfo.Id,
30
                                            Scope,
31
                                            CompanyName(),
32
                                            UserSecurityId(),
33
                                            SecretID) then begin
34
            IsolatedStorageRecord."Target Value Type" := IsolatedStorageRecord."Target Value Type"::SecretText;
35
            IsolatedStorageRecord.CalcFields(Value);
36
            IsolatedStorageRecord.Value.CreateInStream(ValueInStream);
37
            ValueInStream.ReadText(ValueText);
38
        end;
39
    end;
40

41
    procedure DataScopeToOption(DataScope: Enum "Data Scope"): Integer
42
    var
43
        IsolatedStorage: Record "Isolated Storage";
44
    begin
45
        case DataScope of
46
            DataScope::Company:
47
                exit(IsolatedStorage.Scope::Company);
48
            DataScope::"CompanyAndUser":
49
                exit(IsolatedStorage.Scope::CompanyAndUser);
50
            DataScope::Module:
51
                exit(IsolatedStorage.Scope::Module);
52
            DataScope::User:
53
                exit(IsolatedStorage.Scope::User);
54
        end;
55
    end;
56
}
57

58
page 50400 "Secrets"
59
{
60
    ApplicationArea = All;
61
    Caption = 'Secrets';
62
    InsertAllowed = false;
63
    PageType = List;
64
    SourceTable = "Secret";
65
    UsageCategory = Administration;
66

67
    layout
68
    {
69
        area(Content)
70
        {
71
            repeater(General)
72
            {
73
                field(Code; Rec.Code)
74
                {
75
                    Editable = false;
76
                    ToolTip = 'Specifies the value of the Code field.';
77
                }
78
                field(Description; Rec.Description)
79
                {
80
                    ToolTip = 'Specifies the value of the Description field.';
81
                }
82
                field("Data Scope"; Rec."Data Scope")
83
                {
84
                    Editable = false;
85
                    ToolTip = 'Specifies the value of the Data Scope field.';
86
                }
87
            }
88
        }
89
    }
90
    actions
91
    {
92

93
        area(Processing)
94
        {
95
            action("Set Secret OnPrem")
96
            {
97
                ApplicationArea = all;
98
                Caption = 'Set Secret OnPrem';
99
                Promoted = true;
100
                PromotedCategory = Process;
101
                ToolTip = 'Allows to set a new secret.';
102
                trigger OnAction()
103
                begin
104
                    this.SetSecretOnPrem();
105
                end;
106
            }
107
            action("Get Secret OnPrem")
108
            {
109
                ApplicationArea = all;
110
                Caption = 'Get Secret OnPrem';
111
                Promoted = true;
112
                PromotedCategory = Process;
113
                ToolTip = 'Allows to get a secret.';
114
                trigger OnAction()
115
                var
116
                    SecretText: Text;
117
                begin
118

119
                    Message(SecretText);
120
                end;
121
            }
122
        }
123
    }
124

125

126
    local procedure SetSecretOnPrem()
127
    var
128
        NewSecret: Record Secret;
129
        SecretDialog: Page "Set Secret Dialog";
130
        SecretText: Text;
131
    begin
132
        if SecretDialog.RunModal() = Action::OK then begin
133
            SecretDialog.SetSecret(NewSecret);
134
            SecretText := SecretDialog.GetSecret();
135

136
            this.IsolatedStorageOnPremOnly.Set(NewSecret, SecretText);
137
            NewSecret.Modify(true);
138

139
            Commit();
140
        end;
141
    end;
142

143
    var
144
        IsolatedStorageOnPremOnly: Codeunit "Isolated Storage - OnPremOnly";
145
}

How Secrets Appear in SQL

When stored in the database, the secret value itself is not visible in plain text. Instead, it is stored in a hashed format inside the BLOB field. Below is an example of the Isolated Storage table in SQL. SQL - Isolated Storage table

Best Practices for Storing Secrets in AL

When working with sensitive data in Business Central extensions, it is important to follow a few key principles.

Always Use Isolated Storage

Never store secrets directly in:

setup tables
configuration tables
page fields

Even with masking enabled, the values can still be accessed through the database or APIs.

Prefer SecretText Over Text

Whenever possible, use the SecretText data type instead of Text.

SecretText ensures that sensitive values are handled securely in memory and are not accidentally exposed in logs or telemetry.

Use the Appropriate DataScope

Choose the scope carefully depending on how the secret should be used:

Module for extension-level secrets
Company for company-specific integrations
User for user tokens
CompanyAndUser for user-specific company data

Avoid Hardcoding Secrets

Never include secrets directly in AL code or configuration files. Instead, retrieve them securely from Isolated Storage at runtime.

Use Encryption When Available

If the environment supports encryption, prefer using SetEncrypted to store sensitive values.

Conclusion

When working with secrets in Business Central, developers should always consider Isolated Storage as the default mechanism for storing sensitive values.

It provides:

isolation between extensions
optional encryption
built-in API support
scope-based access control

For most scenarios where external secret managers like Azure Key Vault are not used, Isolated Storage should be the default choice for storing secrets in AL.

How to Securely Store Secrets in Dynamics 365 Business Central: Isolated Storage

Table of Contents